PHP SDK

Библиотека Anthropic PHP обеспечивает удобный доступ к Claude API из любого приложения на PHP 8.1.0+.

Установка

SDK использует PSR-18 для HTTP и автоматически обнаруживает любой установленный клиент PSR-18. Рекомендуется Guzzle, поскольку SDK настраивает его для «streaming» (потоковой передачи) без дополнительной конфигурации:

composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7"

Требования

PHP 8.1.0 или выше.

Использование

Эта библиотека использует именованные параметры для указания необязательных аргументов. Параметры со значением по умолчанию должны задаваться по имени.

$client = new Client();

$message = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-5',
);

$textBlock = array_find($message->content, static fn ($block): bool => $block->type === 'text');
echo $textBlock->text;

Варианты аутентификации, включая Workload Identity Federation, описаны в разделе Аутентификация. Если ваш ключ API является персональным ключом или ключом сервисного аккаунта с доступом к нескольким рабочим пространствам, укажите идентификатор рабочего пространства в заголовке запроса anthropic-workspace-id; в разделе Выбор рабочего пространства показан вариант настройки для отдельного запроса в этом SDK.

Объекты-значения

Для инициализации «value objects» (объектов-значений) рекомендуется использовать статический конструктор with — Base64ImageSource::with(data: "U3RhaW5sZXNzIHJvY2tz", ...) — и именованные параметры.

Однако также предоставляются построители: (new Base64ImageSource)->withData("U3RhaW5sZXNzIHJvY2tz").

Потоковая передача

SDK поддерживает потоковую передачу ответов с использованием «Server-Sent Events» (событий, отправляемых сервером), или SSE.

$client = new Client();

$stream = $client->messages->createStream(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-5',
);

foreach ($stream as $event) {
  echo $event->type . PHP_EOL;
}

Для потоковой передачи требуется HTTP-клиент, который возвращает тело ответа по частям. Когда обнаруженным клиентом PSR-18 является Guzzle, SDK автоматически настраивает его для потоковой передачи. При использовании буферизующего клиента цикл foreach выдаёт все события сразу после завершения ответа, а не постепенно; если вы наблюдаете такой симптом, установите Guzzle или передайте клиент PSR-18 с поддержкой потоковой передачи через параметр запроса streamingTransporter:

$client = new Anthropic\Client(
  requestOptions: Anthropic\RequestOptions::with(streamingTransporter: $myStreamingClient),
);

Обработка ошибок

Когда библиотеке не удаётся подключиться к API или если API возвращает код состояния, отличный от успешного (то есть ответ 4xx или 5xx), выбрасывается подкласс Anthropic\Core\Exceptions\APIException:

<?php
// ...
use Anthropic\Core\Exceptions\APIConnectionException;
use Anthropic\Core\Exceptions\APIStatusException;
use Anthropic\Core\Exceptions\RateLimitException;
// ...
try {
  $message = $client->messages->create(
    maxTokens: 1024,
    messages: [['role' => 'user', 'content' => 'Hello, Claude']],
    model: 'claude-opus-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();
}

Коды ошибок следующие:

Повторные попытки

Некоторые ошибки по умолчанию автоматически повторяются два раза с короткой экспоненциальной задержкой.

Ошибки соединения (например, из-за проблем с сетевым подключением), 408 Request Timeout, 409 Conflict, 429 Rate Limit («ограничение скорости»), внутренние ошибки >=500 и тайм-ауты по умолчанию повторяются.

Вы можете использовать параметр maxRetries, чтобы настроить или отключить это поведение:

use Anthropic\RequestOptions;
// ...
// Настройте значение по умолчанию для всех запросов:
$client = new Client(requestOptions: RequestOptions::with(maxRetries: 0));

// Или настройте для каждого запроса отдельно:
$result = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-5',
  requestOptions: RequestOptions::with(maxRetries: 5),
);

Пагинация

Методы списков в Claude API поддерживают пагинацию.

Эта библиотека предоставляет итераторы с автоматической пагинацией для каждого ответа со списком, поэтому вам не нужно вручную запрашивать последующие страницы:

$client = new Client();

$page = $client->beta->messages->batches->list(limit: 20);

// получить элементы с текущей страницы
foreach ($page->getItems() as $item) {
  echo $item->id, PHP_EOL;
}
// выполнить дополнительные сетевые запросы для получения элементов со всех страниц, включая текущую и последующие
foreach ($page->pagingEachItem() as $item) {
  echo $item->id, PHP_EOL;
}

Расширенное использование

Недокументированные свойства

Вы можете отправлять недокументированные параметры на любую конечную точку и читать недокументированные свойства ответа следующим образом:

<?php
// ...
use Anthropic\RequestOptions;
// ...
$message = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-5',
  requestOptions: RequestOptions::with(
    extraQueryParams: ['my_query_parameter' => 'value'],
    extraBodyParams: ['my_body_parameter' => 'value'],
    extraHeaders: ['my-header' => 'value'],
  ),
);

Недокументированные параметры запроса

Если вы хотите явно отправить дополнительный параметр, вы можете сделать это с помощью параметров extraQueryParams, extraBodyParams и extraHeaders в RequestOptions::with() при выполнении запроса, как показано в предыдущем примере.

Недокументированные конечные точки

Чтобы выполнять запросы к недокументированным конечным точкам, сохраняя преимущества аутентификации, повторных попыток и других функций клиента, вы можете выполнять запросы с помощью client->request следующим образом:

$client = new Client();

$response = $client->request(
  method: "post",
  path: '/undocumented/endpoint',
  query: ['dog' => 'woof'],
  headers: ['useful-header' => 'interesting-value'],
  body: ['hello' => 'world']
);

Интеграции с платформами

PHP SDK поддерживает следующие платформы:

• Agent Platform: Anthropic\Vertex\Client. Используйте ::fromEnvironment().
• Bedrock: Anthropic\Bedrock\MantleClient. Используйте new MantleClient(awsRegion: ...).
• Bedrock (устаревший): Anthropic\Bedrock\Client. Используйте ::fromEnvironment() или ::withCredentials().
• Claude Platform на AWS: Anthropic\Aws\Client (требует aws/aws-sdk-php в качестве мягкой зависимости). Используйте new Anthropic\Aws\Client(workspaceId: ...) или задайте ANTHROPIC_AWS_WORKSPACE_ID. Доступно в бета-версии.
• Foundry: Anthropic\Foundry\Client. Используйте ::withCredentials().

Используйте MantleClient для новых проектов; Anthropic\Bedrock\Client остаётся для существующих приложений, использующих API Bedrock InvokeModel.

Семантическое версионирование

Этот пакет следует соглашениям SemVer. Поскольку библиотека находится на начальной стадии разработки и имеет мажорную версию 0, API могут измениться в любое время.

Этот пакет считает улучшения определений типов PHPDoc (не влияющих на выполнение) изменениями, не нарушающими обратную совместимость.

Дополнительные ресурсы

• Репозиторий GitHub
• Packagist
• Справочник API
• Потоковая передача сообщений