README

Self-contained Laravel 12 and 13 client for the Elvesora Company Domain Lookup API, with auto-discovery, dependency injection, a facade, typed results and exceptions, and publishable configuration.

Requirements

PHP 8.2 or later
PHP mbstring and json extensions
Laravel 12 or 13
An Elvesora API key

Laravel 13 requires PHP 8.3 or later.

Obtain and manage the key through the Company Domain Lookup documentation. Keep it in server-side configuration; never expose it in browser or mobile client code.

Installation

composer require elvesora/domain-lookup-laravel

The service provider is discovered automatically. This package contains its own API client and does not require elvesora/domain-lookup-php.

Configuration

Add the API key to .env:

ELVESORA_DOMAIN_LOOKUP_API_KEY=your-api-key

Optional settings:

ELVESORA_DOMAIN_LOOKUP_BASE_URL=https://prospecting.elvesora.com/api
ELVESORA_DOMAIN_LOOKUP_TIMEOUT=100
ELVESORA_DOMAIN_LOOKUP_CONNECT_TIMEOUT=10
ELVESORA_DOMAIN_LOOKUP_USER_AGENT=My-Laravel-App/1.0

Timeout values are seconds and must be greater than zero. The connection timeout is capped internally at the total timeout. A custom base URL must be an absolute HTTP or HTTPS URL with a host and cannot contain embedded credentials, a query string, or a fragment. The user agent must be a non-empty string.

Publish the configuration when you need to customize or inspect it:

php artisan vendor:publish --tag=domain-lookup-config

Credentials are checked only when the client is first resolved, so package discovery and unrelated Artisan commands do not require an API key.

Dependency injection

<?php

namespace App\Services;

use Elvesora\DomainLookup\Laravel\Contracts\DomainLookupClientInterface;
use Elvesora\DomainLookup\Laravel\DomainLookupResult;

final class ResolveCompanyDomain
{
    public function __construct(
        private readonly DomainLookupClientInterface $domainLookup,
    ) {
    }

    public function handle(string $companyName): DomainLookupResult
    {
        return $this->domainLookup->lookup($companyName);
    }
}

Facade

use Elvesora\DomainLookup\Laravel\Facades\DomainLookup;

$result = DomainLookup::lookup(
    companyName: 'Acme Corporation',
    additionalContext: 'US software company',
);

if ($result->found) {
    echo $result->domain;
}

Check the API key without consuming lookup allowance:

$health = DomainLookup::ping();

echo $health->status; // ok

Result fields

DomainLookupResult exposes readonly properties for:

companyName, normalizedCompanyName, and message
domain, found, confidence, and isLive
linkedinUrl, industry, subIndustry, and sector
reasons, lowerReasons, and cached
remaining and limit for subscription usage
requestId for support and trace correlation

Use $result->toArray() or json_encode($result) when an array or JSON payload is more convenient. A completed no-match is an HTTP 200 result with found === false, domain === null, and confidence === 0.

companyName must be non-empty and no longer than 255 characters. Optional additionalContext is trimmed, treats an empty string as absent, and cannot exceed 2,000 characters. A custom request ID must be 8 to 128 characters and may contain only letters, numbers, dots, underscores, colons, and hyphens. Invalid local values are rejected before an HTTP request and consume no lookup credit.

Errors and retries

use Elvesora\DomainLookup\Laravel\Exception\DomainLookupException;

try {
    $result = DomainLookup::lookup('Acme Corporation');
} catch (\LogicException $exception) {
    // ELVESORA_DOMAIN_LOOKUP_API_KEY is missing from application configuration.
} catch (\InvalidArgumentException $exception) {
    // Invalid lookup input, client configuration, or request ID.
} catch (DomainLookupException $exception) {
    // Remote authentication, validation, usage-limit, API, response, or transport error.
    report($exception);

    if ($exception->retryable) {
        $retryAfter = $exception->retryAfter;
    }
}

Exception reference

Exception	When it is thrown
`\LogicException`	The Laravel API-key configuration is missing or another required package configuration value is invalid when the client is resolved.
`\InvalidArgumentException`	Client configuration, lookup input, or request ID is invalid; no HTTP request is sent.
`AuthenticationException`	The API returns HTTP 401 for an invalid or revoked key.
`ValidationException`	The API returns HTTP 422. Use `errors()` for field-level validation messages.
`UsageLimitException`	The API returns HTTP 429. Use `limit()` and `remaining()` for available quota metadata.
`ApiException`	The API returns another non-success HTTP response.
`InvalidResponseException`	The API response is not valid JSON, is not a JSON object, or violates the expected result contract.
`TransportException`	The HTTP client cannot complete the request because of a connection, DNS, TLS, or similar transport failure.

All package API exceptions extend Elvesora\DomainLookup\Laravel\Exception\DomainLookupException. It exposes readonly statusCode, errorType, retryable, retryAfter, responseBody, and requestId properties. API keys are never added to exception messages.

The client does not retry automatically. Local validation failures do not reach the API and consume no credit. After an authenticated lookup passes the usage-limit check, completed matches, no-match results, cached results, server-side validation errors, and retryable 502 or 503 responses consume one credit. A request blocked with HTTP 429 consumes no credit. Request IDs are tracing values rather than idempotency keys; make retry decisions explicitly.

Testing applications

Replace the interface binding with a test double; no live HTTP request is needed:

$this->app->instance(
    \Elvesora\DomainLookup\Laravel\Contracts\DomainLookupClientInterface::class,
    $fakeDomainLookupClient,
);

Package development

composer install
composer check

The test suite uses mocked HTTP responses and sends no requests to the live Elvesora API.

License

MIT. See LICENSE.

elvesora / domain-lookup-laravel

Maintainers

Package info

Statistics

Security