> ## 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.

# Ejecutar con el SDK de PHP

> Invoca un deployment de prompt desde PHP con el paquete de Composer fetch-hive/sdk

# Ejecutar con el SDK de PHP

Usa el paquete oficial de Composer `fetch-hive/sdk` cuando quieras invocar un deployment de prompt desde PHP. El SDK envuelve el endpoint público [`POST /v1/prompt/invoke`](../api-reference/prompts/invoke) con una fachada idiomática, maneja la autenticación y expone las respuestas en streaming como un generador de arreglos de eventos analizados.

## Instalación

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

El SDK requiere PHP 8.1+ y usa Guzzle como su cliente HTTP.

## Autenticación

Configura la variable de entorno `FETCH_HIVE_API_KEY` con tu clave de API del workspace (el cliente la lee automáticamente):

```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();
```

O pasa la clave explícitamente:

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

Consulta [API Keys](../workspace/api-keys) para saber cómo crear y rotar claves.

## Ejemplo básico

Invoca un deployment de prompt y lee la respuesta final:

```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` se bloquea hasta que el prompt se completa y devuelve el cuerpo JSON analizado como un arreglo asociativo. Consulta la [forma de respuesta sin streaming](../api-reference/prompts/invoke#response).

## Referencia del método

| Clave        | Tipo     | Requerido | Descripción                                                                                                                                      |
| ------------ | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `deployment` | `string` | Sí        | El nombre del deployment de prompt                                                                                                               |
| `variant`    | `string` | No        | El nombre de la variante del deployment                                                                                                          |
| `inputs`     | `array`  | No        | Pares clave-valor para las variables del prompt                                                                                                  |
| `user`       | `string` | No        | Identificador opaco de quien llama, expuesto en [User Tracking](../user-tracking/overview)                                                       |
| `metadata`   | `array`  | No        | Metadata plana definida por quien llama, para auditoría y filtrado de registros. Consulta [Metadata de invoke](../user-tracking/invoke-metadata) |

El SDK inyecta `streaming: false` para `invokePrompt`. Para transmitir, usa `invokePromptStream` (a continuación).

## Manejo de la respuesta

```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

Usa `invokePromptStream` para recibir Server-Sent Events a medida que llegan. El método devuelve un `Generator` que puedes iterar con `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,
    };
}
```

La transmisión produce los mismos tipos de evento documentados en [Invoke Prompt → Response](../api-reference/prompts/invoke#response): `reasoning`, `response`, un evento `usage` final o un evento `error` si el proveedor falla durante la transmisión.

## Configuración

| Opción     | Predeterminado                           | Descripción                         |
| ---------- | ---------------------------------------- | ----------------------------------- |
| `api_key`  | variable de entorno `FETCH_HIVE_API_KEY` | Token bearer del dashboard          |
| `base_url` | `https://api.fetchhive.com/v1`           | Sobrescribe la URL base de la API   |
| `timeout`  | `120`                                    | Timeout de la solicitud en segundos |

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

## Errores

Las respuestas distintas a 2xx lanzan `FetchHive\Sdk\Exception\ApiException` con el código de estado y el cuerpo de la respuesta. Captúralas si necesitas manejar fallos:

```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());
}
```

Consulta [Errors and Rate Limits](../api-reference/errors-and-rate-limits) para el significado de los códigos de estado.

## Enlaces

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

## Siguientes pasos

* [Ejecutar con API](./run-with-api) - El mismo flujo con cURL
* [Ejecutar con el SDK de Python](./run-with-python-sdk)
* [Ejecutar con el SDK de Node.js](./run-with-nodejs-sdk)
* [Ejecutar con el SDK de Ruby](./run-with-ruby-sdk)
* [Invoke Prompt](../api-reference/prompts/invoke) - Referencia completa del endpoint