--- title: PHP SDK url: https://platform.claude.com/docs/es/cli-sdks-libraries/sdks/php description: Instala y configura el SDK de PHP de Anthropic con objetos de valor y patrones de construcción --- La biblioteca PHP de Anthropic proporciona acceso conveniente a la API de Claude desde cualquier aplicación PHP 8.1.0+. Para consultar la documentación de las funciones de la API con ejemplos de código, consulta la [referencia de la API](https://platform.claude.com/docs/es/api/overview). Esta página cubre las funciones y la configuración específicas del SDK de PHP. ## Instalación El SDK usa [PSR-18](https://www.php-fig.org/psr/psr-18/) para HTTP y detecta automáticamente cualquier cliente PSR-18 instalado. Se recomienda [Guzzle](https://docs.guzzlephp.org/) porque el SDK lo configura para "streaming" (transmisión incremental) sin configuración adicional: ```bash composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7" ``` ## Requisitos PHP 8.1.0 o superior. ## Uso Esta biblioteca usa parámetros con nombre para especificar argumentos opcionales. Los parámetros con un valor predeterminado deben establecerse por nombre. ```php $client = new Client(); $message = $client->messages->create( maxTokens: 1024, messages: [['role' => 'user', 'content' => 'Hello, Claude']], model: 'claude-opus-5-5', ); $textBlock = array_find($message->content, static fn ($block): bool => $block->type === 'text'); echo $textBlock->text; ``` Para conocer las opciones de autenticación, incluida "Workload Identity Federation" (federación de identidades de carga de trabajo), consulta [Autenticación](https://platform.claude.com/docs/es/manage-claude/authentication). Si tu "API key" (clave de API) es una [clave personal o de cuenta de servicio](https://platform.claude.com/docs/es/manage-claude/authentication#key-types) que no está limitada a un espacio de trabajo, establece el ID del espacio de trabajo en el encabezado de solicitud `anthropic-workspace-id`; [Seleccionar un espacio de trabajo](https://platform.claude.com/docs/es/manage-claude/authentication#select-a-workspace) muestra la opción por solicitud para este SDK. ## Objetos de valor Se recomienda usar el constructor estático `with` `Base64ImageSource::with(data: "U3RhaW5sZXNzIHJvY2tz", ...)` y parámetros con nombre para inicializar objetos de valor. Sin embargo, también se proporcionan constructores (builders) `(new Base64ImageSource)->withData("U3RhaW5sZXNzIHJvY2tz")`. ## Streaming El SDK ofrece soporte para respuestas en streaming mediante "Server-Sent Events" (eventos enviados por el servidor), o SSE. ```php $client = new Client(); $stream = $client->messages->createStream( maxTokens: 1024, messages: [['role' => 'user', 'content' => 'Hello, Claude']], model: 'claude-opus-5-5', ); foreach ($stream as $event) { echo $event->type . PHP_EOL; } ``` El streaming requiere un cliente HTTP que devuelva el cuerpo de la respuesta de forma incremental. Cuando Guzzle es el cliente PSR-18 detectado, el SDK lo configura automáticamente para streaming. Con un cliente que almacena en búfer, el bucle `foreach` entrega todos los eventos a la vez cuando la respuesta se completa en lugar de hacerlo de forma incremental; si observas ese síntoma, instala Guzzle o proporciona un cliente PSR-18 compatible con streaming mediante la opción de solicitud `streamingTransporter`: ```php $client = new Client( requestOptions: RequestOptions::with(streamingTransporter: $myStreamingClient), ); ``` ## Manejo de errores Cuando la biblioteca no puede conectarse a la API, o si la API devuelve un código de estado que no es de éxito (es decir, una respuesta 4xx o 5xx), se lanza una subclase de `Anthropic\Core\Exceptions\APIException`: ```php messages->create( maxTokens: 1024, messages: [['role' => 'user', 'content' => 'Hello, Claude']], model: 'claude-opus-5-5', ); } catch (APIConnectionException $e) { echo "The server could not be reached", PHP_EOL; echo $e->getPrevious()?->getMessage(), PHP_EOL; } catch (RateLimitException $_) { echo "A 429 status code was received; we should back off a bit.", PHP_EOL; } catch (APIStatusException $e) { echo "Another non-200-range status code was received", PHP_EOL; echo $e->getMessage(); } ``` Los códigos de error son los siguientes: | Causa | Tipo de error | | ------------------------ | ------------------------------ | | HTTP 400 | `BadRequestException` | | HTTP 401 | `AuthenticationException` | | HTTP 403 | `PermissionDeniedException` | | HTTP 404 | `NotFoundException` | | HTTP 409 | `ConflictException` | | HTTP 422 | `UnprocessableEntityException` | | HTTP 429 | `RateLimitException` | | HTTP >= 500 | `InternalServerException` | | Otro error HTTP | `APIStatusException` | | Tiempo de espera agotado | `APITimeoutException` | | Error de red | `APIConnectionException` | ## Reintentos Ciertos errores se reintentan automáticamente dos veces de forma predeterminada, con un breve retroceso exponencial. Los errores de conexión (por ejemplo, debido a un problema de conectividad de red), 408 Request Timeout, 409 Conflict, 429 Rate Limit, los errores internos >=500 y los tiempos de espera agotados se reintentan de forma predeterminada. Puedes usar la opción `maxRetries` para configurar o desactivar esto: ```php use Anthropic\RequestOptions; // ... // Configura el valor predeterminado para todas las solicitudes: $client = new Client(requestOptions: RequestOptions::with(maxRetries: 0)); // O bien, configúralo por solicitud: $result = $client->messages->create( maxTokens: 1024, messages: [['role' => 'user', 'content' => 'Hello, Claude']], model: 'claude-opus-5-5', requestOptions: RequestOptions::with(maxRetries: 5), ); ``` ## Paginación Los métodos de listado de la API de Claude están paginados. Esta biblioteca proporciona iteradores con paginación automática en cada respuesta de listado, para que no tengas que solicitar las páginas sucesivas manualmente: ```php $client = new Client(); $page = $client->beta->messages->batches->list(limit: 20); // obtiene los elementos de la página actual foreach ($page->getItems() as $item) { echo $item->id, PHP_EOL; } // realiza solicitudes de red adicionales para obtener elementos de todas las páginas, incluida la actual y las siguientes // ... foreach ($page->pagingEachItem() as $item) { echo $item->id, PHP_EOL; // ... } ``` ## Uso avanzado ### Trazado de OpenTelemetry Cuando tu aplicación registra un tracer provider de OpenTelemetry, el SDK emite un span por cada solicitud que envía. Para enviar los spans a tu plataforma de observabilidad, consulta [Configura OpenTelemetry con el Claude SDK](https://platform.claude.com/docs/es/manage-claude/opentelemetry/sdk). ### Propiedades no documentadas Puedes enviar parámetros no documentados a cualquier endpoint y leer propiedades de respuesta no documentadas, de la siguiente manera: Los parámetros `extra*` con el mismo nombre sobrescriben los parámetros documentados. ```php messages->create( maxTokens: 1024, messages: [['role' => 'user', 'content' => 'Hello, Claude']], model: 'claude-opus-5-5', requestOptions: RequestOptions::with( extraQueryParams: ['my_query_parameter' => 'value'], extraBodyParams: ['my_body_parameter' => 'value'], extraHeaders: ['my-header' => 'value'], ), ); ``` ### Parámetros de solicitud no documentados Si quieres enviar explícitamente un parámetro adicional, puedes hacerlo con las opciones `extraQueryParams`, `extraBodyParams` y `extraHeaders` en `RequestOptions::with()` al realizar una solicitud, como se ve en el ejemplo anterior. ### Endpoints no documentados Para realizar solicitudes a endpoints no documentados conservando los beneficios de la autenticación, los reintentos y otras funciones del cliente, puedes realizar solicitudes usando `client->request`, de la siguiente manera: ```php $client = new Client(); $response = $client->request( method: "post", path: '/undocumented/endpoint', query: ['dog' => 'woof'], headers: ['useful-header' => 'interesting-value'], body: ['hello' => 'world'] ); ``` ## Integraciones de plataforma Para consultar guías detalladas de configuración de plataformas con ejemplos de código, consulta: * [Amazon Bedrock](https://platform.claude.com/docs/es/build-with-claude/claude-in-amazon-bedrock) * [Amazon Bedrock (Opus 4.6 y anteriores)](https://platform.claude.com/docs/es/build-with-claude/claude-on-amazon-bedrock-legacy) * [Claude Platform on AWS](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws) * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/google-managed) * [Microsoft Foundry](https://platform.claude.com/docs/es/build-with-claude/claude-in-microsoft-foundry) Consulta también [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/anthropic-managed). El SDK de PHP es compatible con las siguientes plataformas: * **Agent Platform:** `Anthropic\Vertex\Client`. Usa `::fromEnvironment()`. * **Bedrock:** `Anthropic\Bedrock\MantleClient`. Usa `new MantleClient(awsRegion: ...)`. * **Bedrock (heredado):** `Anthropic\Bedrock\Client`. Usa `::fromEnvironment()` o `::withCredentials()`. * **Claude Platform on AWS:** `Anthropic\Aws\Client` (requiere `aws/aws-sdk-php` como dependencia opcional). Usa `new Anthropic\Aws\Client(workspaceId: ...)` o establece `ANTHROPIC_AWS_WORKSPACE_ID`. Disponible en beta. * **Foundry:** `Anthropic\Foundry\Client`. Usa `::withCredentials()`. Usa `MantleClient` para proyectos nuevos; `Anthropic\Bedrock\Client` se mantiene para las aplicaciones existentes que usan la API `InvokeModel` de Bedrock. El SDK de PHP también es compatible con Claude Models on Google Cloud (Anthropic managed) a través de `Anthropic\GoogleCloud\Client`. Este cliente está en beta. `Anthropic\GoogleCloud\Client` requiere `google/auth` como dependencia opcional. Usa `new Anthropic\GoogleCloud\Client(workspaceId: ...)` o establece la variable de entorno `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID`. Consulta [Resolución del proyecto, la ubicación y el workspace](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution). ## Versionado semántico Cada versión principal de este SDK envía una versión de la API en el encabezado `anthropic-version` de forma predeterminada, y cada nueva versión de la API viene acompañada de una nueva versión principal. La primera versión principal que envía `2026-10-21` es la 1.0.0; consulta [Actualizar a 2026-10-21](https://platform.claude.com/docs/es/api/migration-2026-10-21#upgrade). Este paquete sigue las convenciones de [SemVer](https://semver.org/spec/v2.0.0.html). Este paquete considera que las mejoras en las definiciones de tipos de PHPDoc (que no son de tiempo de ejecución) son cambios que no rompen la compatibilidad. ## Recursos adicionales * [Repositorio de GitHub](https://github.com/anthropics/anthropic-sdk-php) * [Packagist](https://packagist.org/packages/anthropic-ai/sdk) * [Referencia de la API](https://platform.claude.com/docs/es/api/overview) * [Streaming de mensajes](https://platform.claude.com/docs/es/build-with-claude/streaming)