> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run with PHP SDK

> Invoke a prompt deployment from PHP with the fetch-hive/sdk Composer package

Use the official `fetch-hive/sdk` Composer package when you want to invoke a prompt deployment from PHP. The SDK wraps the public [`POST /v1/prompt/invoke`](../api-reference/invoke-prompt) endpoint with an idiomatic facade, handles authentication, and exposes streaming responses as a generator of parsed event arrays.

## Installation

```bash theme={null}
composer require fetch-hive/sdk
```

The SDK requires PHP 8.1+ and uses Guzzle as its HTTP client.

## Authentication

Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key (the client reads it automatically):

```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```

```php theme={null}
<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive();
```

Or pass the key explicitly:

```php theme={null}
$client = new FetchHive(['api_key' => 'fhk_...']);
```

See [API Keys](../workspace/api-keys) for how to create and rotate keys.

## Basic example

Invoke a prompt deployment and read the final response:

```php theme={null}
<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive();

$result = $client->invokePrompt([
    'deployment' => 'YOUR_DEPLOYMENT_NAME',
    'variant'    => 'YOUR_VARIANT_NAME',
    'inputs'     => ['text' => 'Fetch Hive helps teams ship AI products faster.'],
]);

echo $result['response'];
```

`invokePrompt` blocks until the prompt completes and returns the parsed JSON body as an associative array. See the [non-streaming response shape](../api-reference/invoke-prompt#response).

## Method reference

| Key          | Type     | Required | Description                                                                                                       |
| ------------ | -------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `deployment` | `string` | Yes      | The prompt deployment name                                                                                        |
| `variant`    | `string` | No       | The deployment variant name                                                                                       |
| `inputs`     | `array`  | No       | Key-value pairs for the prompt variables                                                                          |
| `user`       | `string` | No       | Opaque caller identifier surfaced in [User Tracking](../user-tracking/overview)                                   |
| `metadata`   | `array`  | No       | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |

The SDK injects `streaming: false` for `invokePrompt`. To stream, use `invokePromptStream` (below).

## Handling the response

```php theme={null}
$result = $client->invokePrompt([
    'deployment' => 'my-prompt',
    'variant'    => 'default',
]);

echo $result['response'];      // final text
echo $result['model'];         // model identifier
print_r($result['usage']);     // token usage breakdown
echo $result['request_id'];    // use this to look up the run in Logs
```

## Streaming

Use `invokePromptStream` to receive Server-Sent Events as they arrive. The method returns a `Generator` you can iterate with `foreach`:

```php theme={null}
foreach ($client->invokePromptStream([
    'deployment' => 'YOUR_DEPLOYMENT_NAME',
    'variant'    => 'YOUR_VARIANT_NAME',
    'inputs'     => ['text' => 'Fetch Hive helps teams ship AI products faster.'],
]) as $chunk) {
    match ($chunk['type']) {
        'response' => print($chunk['response'] ?? ''),
        'usage'    => print("\n\nUsage: " . json_encode($chunk['usage'])),
        default    => null,
    };
}
```

The stream yields the same event types documented in [Invoke Prompt → Response](../api-reference/invoke-prompt#response): `reasoning`, `response`, a final `usage` event, or an `error` event if the provider fails mid-stream.

## Configuration

| Option     | Default                        | Description                     |
| ---------- | ------------------------------ | ------------------------------- |
| `api_key`  | `FETCH_HIVE_API_KEY` env var   | Bearer token from the dashboard |
| `base_url` | `https://api.fetchhive.com/v1` | Override the API base URL       |
| `timeout`  | `120`                          | Request timeout in seconds      |

```php theme={null}
$client = new FetchHive([
    'api_key'  => 'fhk_...',
    'base_url' => 'https://api.fetchhive.com/v1',
    'timeout'  => 60.0,
]);
```

## Errors

Non-2xx responses throw `FetchHive\Sdk\Exception\ApiException` carrying the status code and response body. Catch it if you need to handle failures:

```php theme={null}
use FetchHive\Sdk\Exception\ApiException;

try {
    $result = $client->invokePrompt([
        'deployment' => 'my-prompt',
        'variant'    => 'default',
    ]);
} catch (ApiException $e) {
    error_log('Fetch Hive error: ' . $e->getMessage());
}
```

See [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for status code meanings.

## Links

* [Package on Packagist](https://packagist.org/packages/fetch-hive/sdk)
* [Source on GitHub](https://github.com/Fetch-Hive/php-sdk)

## Next steps

* [Run with API](./run-with-api) - The same flow with cURL
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Invoke Prompt](../api-reference/invoke-prompt) - Full endpoint reference