Download the PHP package elvesora/enrichment-php without Composer

Elvesora Enrichment for PHP

A framework-independent PHP client for turning a business domain into a structured company profile with the Elvesora Company Enrichment API.

Requirements

• PHP 8.2 or later
• PHP json and mbstring extensions
• An Elvesora API key

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

Installation

Quick start

The package does not load a .env file. If your application uses a dotenv library or framework environment loader, initialize it before reading the key and constructing the client.

domain must be non-empty and no longer than 255 characters. The optional idempotency key is trimmed, treats an empty string as absent, cannot exceed 255 characters, and cannot contain control characters. Invalid local input throws InvalidArgumentException before an HTTP request is sent.

Results

Successful API responses return an immutable EnrichmentResult. It exposes readonly properties for:

• success, resultType, and message
• data, containing the structured company fields returned by the API
• domain, derived from the top-level response or company data when available
• credits, an immutable CreditMetadata object
• statusCode, responseCode, and idempotencyStatus

Use $result->isEnriched() to test for an ENRICHED result, $result->wasReplayed() to detect a cached idempotent replay, and $result->toArray() or json_encode($result) when the original response shape is more convenient.

CreditMetadata exposes limit, used, remaining, consumedByRequest, periodStartedAt, and periodEndsAt, plus toArray() and JSON serialization.

Non-chargeable business responses

The API uses HTTP 400 when the domain was understood but no chargeable enrichment was produced. Current result types include NOT_FOUND, FREE_EMAIL_PROVIDER, DISPOSABLE, and INVALID_DOMAIN. These responses throw ApiException because they are non-success HTTP responses, while preserving resultType, responseBody, and any returned credits metadata:

Errors

Exception reference

All SDK exceptions extend EnrichmentException. It exposes readonly statusCode, resultType, retryable, retryAfter, responseBody, credits, and idempotencyStatus properties. Credit metadata is optional on exceptions because authentication and request-validation responses may not include it. API keys are never added to exception messages.

Exception selection is based on result_type before HTTP status. This preserves upstream failures correctly when the API returns UPSTREAM_ERROR with the upstream status code.

Idempotency and credits

Only an ENRICHED result consumes one credit. HTTP 400 business outcomes, request validation failures, authentication failures, credit-limit rejections, idempotency conflicts, and server or upstream errors do not consume a credit.

Pass an idempotency key when a request may be retried. Responses are retained for 24 hours. Reusing the same key with the same domain returns the retained response without consuming another credit and sets Idempotency-Status: replayed; reusing it with a different domain throws IdempotencyConflictException and sets its idempotencyStatus to conflict when the header is present.

The client does not retry automatically. Automatic retries can create duplicate credit consumption when no idempotency key is supplied. Decide whether to retry from the exception's retryable and retryAfter properties, and reuse the original idempotency key for the same domain.

Configuration

The default endpoint is https://enrichment.elvesora.com/api/v1/enrichment/company. HTTP and HTTPS custom base URLs are accepted so local and test environments can use the same client.

Timeout values are seconds and must be greater than zero. connectTimeout 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.

You may pass a custom Guzzle client as the second constructor argument. This supports shared handlers, proxies, observability middleware, and deterministic tests.

Development

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

License

MIT. See LICENSE.