# PHP SDK

The official PHP client for the Synthient API: IP and domain lookups, account details, real-time feed streams, and Parquet exports.

> **Note**: The package is published on [Packagist](https://packagist.org/packages/synthient/synthient-php). There is no hosted API reference: every class is documented in PHPDoc in the source. These pages cover the same surface with examples. The source and runnable programs, in `examples/`, are at [github.com/synthient/synthient-php](https://github.com/synthient/synthient-php).

## Getting started

### 1. Install

```bash
composer require synthient/synthient-php
```

Requires a 64-bit build of PHP 8.3 or later, and Guzzle 7.15.2 or later, or 8.0.1 or later. Guzzle uses the cURL extension when it is available. With the default HTTP client, streams and downloads go through Guzzle's PHP stream handler, so they need the `allow_url_fopen` ini setting, which is on by default. The client is `Synthient\Client`. Response models live in `Synthient\Model`, stream events in `Synthient\Event`, value sets in `Synthient\Enum`, and exceptions in `Synthient\Exception`. Unlike the other SDKs, this package has no [gRPC schema](#g-rpc-schema) fetcher.

### 2. Make your first lookup

This program creates a client and looks up one address, which costs one credit.

```php
<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

$client = new Synthient\Client();

$info = $client->lookupIp('8.8.8.8');
if ($info->network !== null) {
    echo $info->network->isp, ' ', $info->network->type, "\n";
}
if ($info->intelligence !== null) {
    echo $info->intelligence->riskScore, ' ', implode(', ', $info->intelligence->categories), "\n";
}
```

With no arguments, the client reads the API key from the `SYNTHIENT_API_KEY` environment variable. `IpInfo::$network`, `IpInfo::$location`, and `IpInfo::$intelligence` are `null` when the API has no data for that section, so check them before reading their properties.

### 3. Check your credits

`account()` returns the account that owns the API key, including its scopes and remaining lookup credits. It costs no credits.

```php
$account = $client->account();
echo $account->email, ' ', $account->organization->name, ' ', implode(', ', $account->scopes), "\n";
echo $account->lookupQuota->credits, ' credits, resetting in ', $account->lookupQuota->resetsIn, " seconds\n";
```

### 4. Handle errors

Every error the SDK throws at runtime extends `SynthientException`, which extends `\RuntimeException`. Invalid arguments throw `\InvalidArgumentException` instead, before any request is made.

```php
use Synthient\Exception\ApiException;

try {
    $info = $client->lookupIp('8.8.8.8');
    echo $info->ip, "\n";
} catch (ApiException $e) {
    if ($e->statusCode === 402) {
        echo "out of lookup credits\n";
    } elseif ($e->statusCode === 429 && $e->retryAfter !== null) {
        echo "rate limited, retry after {$e->retryAfter} seconds\n";
    } elseif ($e->statusCode === 429) {
        echo "monthly request budget spent\n";
    } else {
        echo "request {$e->requestId} failed: ", $e->detail ?? $e->title, "\n";
    }
}
```

### 5. Keep going

- [Client](https://docs.synthient.com/sdks/php/client): create and configure the client, and read the metadata of every API response.
- [Lookups](https://docs.synthient.com/sdks/php/lookups): look up IP addresses and domains, and check your account and the API's health.
- [Feeds](https://docs.synthient.com/sdks/php/feeds): stream each feed's real-time events and download its hourly and daily Parquet exports.
- [Errors and retries](https://docs.synthient.com/sdks/php/errors): how failed requests are reported, and which requests are retried.
- [Types](https://docs.synthient.com/sdks/php/types): the fields of every response and event type, and the enumerations they use.

## gRPC schema

This package has no gRPC schema fetcher, because PHP's gRPC support needs a compiled extension. To get the protobuf schema of the Synthient [gRPC API](https://docs.synthient.com/grpc), use the gRPC schema fetcher of the [Node](https://docs.synthient.com/sdks/node/grpc-schema), [Python](https://docs.synthient.com/sdks/python/grpc-schema), [Java](https://docs.synthient.com/sdks/java/grpc-schema), [C#](https://docs.synthient.com/sdks/csharp/grpc-schema), [Go](https://docs.synthient.com/sdks/go/grpc-schema), [Rust](https://docs.synthient.com/sdks/rust/grpc-schema), or [Ruby](https://docs.synthient.com/sdks/ruby/grpc-schema) SDK, or any gRPC reflection client such as [grpcurl](https://github.com/fullstorydev/grpcurl).