Client

Create and configure the client, and read the metadata of every API response.

Synthient\Client is a final class. Create one and reuse it for every request. Constructing it makes no requests, and it has no close() method.

Constructor

Every argument is optional, so pass the ones you need by name.

public function __construct(
    #[\SensitiveParameter]
    ?string $apiKey = null,
    string $baseUrl = self::DEFAULT_BASE_URL,
    int $maxRetries = 2,
    float $connectTimeout = 10.0,
    float $timeout = 60.0,
    ?ClientInterface $httpClient = null,
    ?string $userAgent = null,
    ?Closure $responseHook = null,
)

Name
apiKey
Type
?string
Description
The API key. When it is null, the key is read from the SYNTHIENT_API_KEY environment variable. Surrounding whitespace is trimmed. An empty key, or one containing anything other than printable ASCII without spaces, throws \InvalidArgumentException.
Name
baseUrl
Type
string
Description
The API base URL, including the version path. The default is Client::DEFAULT_BASE_URL. It must be an http or https URL with a host and no query, fragment, or credentials.
Name
maxRetries
Type
int
Description
How many times a failed request is retried. The default is 2, 0 disables retries, and a negative value throws. See Retries and timeouts.
Name
connectTimeout
Type
float
Description
Seconds to wait for a connection. The default is 10.0, and it must be at least 0.001. Guzzle's stream handler, which serves streams, downloads, and every request when the cURL extension is missing, ignores it and waits up to timeout for the connection instead.
Name
timeout
Type
float
Description
Seconds each attempt waits for a whole response, or for the next data on a stream or download. The default is 60.0, and it must be at least 0.001. Retries get a fresh timeout, so it does not bound a whole call.
Name
httpClient
Type
?ClientInterface
Description
A Guzzle client (GuzzleHttp\ClientInterface), for proxies, TLS settings, or a custom handler. See the notes below.
Name
userAgent
Type
?string
Description
Appended to the User-Agent header, such as "my-app/1.2". The header starts with synthient-php/ followed by the SDK version, Client::VERSION. It must be printable ASCII and not blank.
Name
responseHook
Type
(Closure(ResponseMetadata): void)|null
Description
Called with every API response. See Response metadata.

$client = new Synthient\Client(
    maxRetries: 4,
    userAgent: 'my-app/1.0',
);

$client = new Synthient\Client(
    httpClient: new GuzzleHttp\Client(['proxy' => 'http://proxy.internal:3128']),
);

Input: An invalid argument throws \InvalidArgumentException.
Security: #[\SensitiveParameter] keeps the key out of stack traces.
HTTP client: A Guzzle client passed as httpClient keeps its defaults, such as proxy, verify, and cert, except that the SDK sets allow_redirects, http_errors, stream, and the timeouts on every request. Export downloads drop the client's default headers, cookies, and auth. The client must not retry requests or set a default query.
Connection: On billed lookups and health() the SDK adds CURLOPT_FRESH_CONNECT to the client's curl option. Those requests are sent without it through Guzzle's stream handler, which never reuses connections, and throw \InvalidArgumentException through a client that requires persistent cURL sharing.
Streaming: Streams and downloads need a handler that streams response bodies. Guzzle's default handler does only when the allow_url_fopen ini setting is on. With the SDK's default HTTP client, streams and downloads throw SynthientException before sending a request when it is off. The SDK checks the setting only for its own default client, so through a client passed as httpClient a stream without it buffers until timeout runs out.

Constants

Name
Client::VERSION
Type
string
Description
The SDK version, such as "1.0.0". It is sent in the User-Agent header.
Name
Client::DEFAULT_BASE_URL
Type
string
Description
"https://api.synthient.com/api/v4", the base URL of the Synthient HTTP API.
Name
Client::MAX_BATCH_SIZE
Type
int
Description
1000, the most addresses lookupIps() accepts in one call.

Response metadata

responseHook is called with a ResponseMetadata after every API response.

use Synthient\ResponseMetadata;

$client = new Synthient\Client(
    responseHook: function (ResponseMetadata $meta): void {
        if ($meta->rateLimit !== null) {
            echo $meta->statusCode, ' ', $meta->requestId, ' ', $meta->rateLimit->remaining, ' ', $meta->rateLimit->reset, "\n";
        }
    },
);

Coverage: It is called for retries, export pages, stream handshakes, export redirects, errors, and responses that then fail to decode. Storage responses from export downloads are excluded, and a transport failure produces no call.

ResponseMetadata

Name
statusCode
Type
int
Description
The HTTP status code of the response.
Name
requestId
Type
?string
Description
The X-Request-Id header, which support can trace, or null if the response has none.
Name
rateLimit
Type
?RateLimit
Description
The rate limit state, or null when the response has no complete RateLimit-* headers.
Name
headers
Type
string[][]
Description
The response headers. An export redirect's Location is a presigned URL, so treat it as a secret.

RateLimit

The rate limit state from the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. Limits apply per team and are shared by all of its keys. See Rate Limits.

Name
limit
Type
int
Description
The burst size of the operation's bucket.
Name
remaining
Type
int
Description
The number of requests left in the bucket.
Name
reset
Type
int
Description
Seconds until the bucket is full again. A negative header value is reported as 0.