# Run with PHP SDK

Use the official `fetch-hive/sdk` Composer package when you want to invoke a workflow deployment from PHP. The SDK wraps the public [`POST /v1/workflow/invoke`](/api-reference/invoke-workflow.md) endpoint, handles authentication, and supports both synchronous and asynchronous runs.

## Installation

```bash
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
export FETCH_HIVE_API_KEY=fhk_...
```

```php
<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive();
```

Or pass the key explicitly:

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

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

## Basic example

Run a workflow deployment synchronously — the call blocks until the workflow finishes:

```php
<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive();

$run = $client->invokeWorkflow([
    'deployment' => 'YOUR_DEPLOYMENT_NAME',
    'variant'    => 'YOUR_VARIANT_NAME',
    'inputs'     => ['topic' => 'State of enterprise AI in 2026'],
]);

echo $run['run_status'] . PHP_EOL;
echo $run['output'];
```

See the [sync response shape](/api-reference/invoke-workflow.md#response).

## Method reference

| Key            | Type     | Required | Description                                                                            |
| -------------- | -------- | -------- | -------------------------------------------------------------------------------------- |
| `deployment`   | `string` | Yes      | The workflow deployment name                                                           |
| `variant`      | `string` | No       | The deployment variant name                                                            |
| `inputs`       | `array`  | No       | Key-value pairs for the variables defined on the **Start** step                        |
| `async_mode`   | `bool`   | No       | When `true`, return immediately and deliver the result via webhook                     |
| `callback_url` | `string` | No       | Required when `async_mode: true` — the HTTPS webhook URL to call when the run finishes |
| `user`         | `string` | No       | Opaque caller identifier surfaced in [User Tracking](/user-tracking/user-tracking.md)  |

`invokeWorkflow` builds the request body for you. When you pass `async_mode: true`, the SDK sends:

```json
{
  "async": { "enabled": true, "callback_url": "https://example.com/webhook" }
}
```

## Handling the response

```php
$run = $client->invokeWorkflow([
    'deployment' => 'my-workflow',
    'variant'    => 'default',
]);

echo $run['run_status'];      // "completed" | "failed" | "running" | "queued"
echo $run['output'];          // final workflow output
echo $run['request_id'];      // use this to look up the run in Logs
```

## Async runs and webhooks

Pass `async_mode: true` to queue the workflow and have Fetch Hive call your webhook when the run finishes:

```php
$run = $client->invokeWorkflow([
    'deployment'   => 'YOUR_DEPLOYMENT_NAME',
    'variant'      => 'YOUR_VARIANT_NAME',
    'inputs'       => ['topic' => 'State of enterprise AI in 2026'],
    'async_mode'   => true,
    'callback_url' => 'https://example.com/callback',
]);

echo 'Queued: ' . $run['run_status'] . PHP_EOL;
echo 'Webhook secret: ' . $run['webhook_secret'];
```

Store the `webhook_secret` so you can verify the signature on the incoming callback. See [Async and Webhooks](/workflows/async-and-webhooks.md) for the verification flow and signed payload shape.

## 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 — increase for long-running synchronous workflows |

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

## Errors

Non-2xx responses throw `FetchHive\Sdk\Exception\ApiException` carrying the status code and response body:

```php
use FetchHive\Sdk\Exception\ApiException;

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

See [Error Handling](/workflows/error-handling.md) for workflow-specific failure cases and [Errors and Rate Limits](/api-reference/errors-and-rate-limits.md) for HTTP 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

* [Async and Webhooks](/workflows/async-and-webhooks.md) - Verify callback signatures
* [Run with API](/workflows/run-with-api.md) - The same flow with cURL
* [Run with Python SDK](/workflows/run-with-python-sdk.md)
* [Run with Node.js SDK](/workflows/run-with-nodejs-sdk.md)
* [Run with Ruby SDK](/workflows/run-with-ruby-sdk.md)
* [Invoke Workflow](/api-reference/invoke-workflow.md) - Full endpoint reference


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fetchhive.com/workflows/run-with-php-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.