Claude Platform Docs
SDK, CLI и библиотекиКлиентские SDK

PHP SDK

Установка и настройка Anthropic 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-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', ...) с именованными параметрами.

Однако также предоставляются «builders» (построители), например (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: Model::CLAUDE_OPUS_5_5,
);

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

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

$client = new Client(
    requestOptions: 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;
use Anthropic\Messages\Model;

try {
    $message = $client->messages->create(
        maxTokens: 1024,
        messages: [['role' => 'user', 'content' => 'Hello, Claude']],
        model: 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();
}

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

ПричинаТип ошибки
HTTP 400BadRequestException
HTTP 401AuthenticationException
HTTP 403PermissionDeniedException
HTTP 404NotFoundException
HTTP 409ConflictException
HTTP 422UnprocessableEntityException
HTTP 429RateLimitException
HTTP >= 500InternalServerException
Другая ошибка HTTPAPIStatusException
Тайм-аутAPITimeoutException
Сетевая ошибкаAPIConnectionException

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

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

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

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

use Anthropic\Messages\Model;
use Anthropic\RequestOptions;

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

// Или настройте для отдельного запроса:
$result = $client->messages->create(
    maxTokens: 1024,
    messages: [['role' => 'user', 'content' => 'Hello, Claude']],
    model: Model::CLAUDE_OPUS_5_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;

}

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

Трассировка OpenTelemetry

Когда ваше приложение регистрирует провайдер трассировщика OpenTelemetry, SDK создаёт спан для каждого отправляемого запроса. Чтобы отправлять спаны на вашу платформу наблюдаемости, см. Настройка OpenTelemetry с Anthropic SDK.

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

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

<?php

use Anthropic\RequestOptions;

$message = $client->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'],
    ),
);

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

Если вы хотите явно отправить дополнительный параметр, вы можете сделать это с помощью параметров 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']
);

Промежуточное ПО

«Middleware» (промежуточное ПО) выполняет ваш код вокруг каждого HTTP-запроса, отправляемого клиентом. В разделе Middleware в SDK показано, как зарегистрировать промежуточное ПО и в каком порядке выполняются несколько обработчиков. В этом разделе описаны детали, специфичные для PHP SDK.

Промежуточное ПО — это вызываемый объект, принимающий запрос и $next, или экземпляр класса, реализующего Anthropic\Middleware, метод handle() которого имеет ту же сигнатуру. Параметр запроса middleware принимает оба варианта:

use Anthropic\Middleware;
use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;

final class TracingMiddleware implements Middleware
{
    public function handle(RequestInterface $request, \Closure $next): ResponseInterface
    {
        return $next($request->withHeader('x-trace-id', bin2hex(random_bytes(8))));
    }
}

$client = new Client(requestOptions: ['middleware' => [new TracingMiddleware()]]);

$next выполняет оставшуюся часть цепочки и отправляет запрос. Вызовите его один раз, чтобы передать запрос дальше, пропустите вызов, чтобы вернуть собственный ответ (например, из кэша), или вызовите его несколько раз, чтобы отправить последующие запросы (например, для собственной логики повторных попыток).

SDK также передаёт каждому промежуточному ПО третий аргумент: Anthropic\RequestOptions запроса, который объединяет параметры клиента с параметрами вызова. Чтобы прочитать такой параметр, как fallbackState, объявите необязательный третий параметр ?RequestOptions $options = null. Считайте этот объект доступным только для чтения, поскольку он общий для всего промежуточного ПО и всех повторных попыток запроса. Если у вашего вызываемого объекта уже есть третий параметр с другим назначением, перепишите его, поскольку SDK заполняет этот параметр при каждом вызове.

Во время выполнения:

  • Повторные попытки: промежуточное ПО выполняется один раз для каждой HTTP-попытки внутри цикла повторных попыток SDK, поэтому оно выполняется снова при каждой повторной попытке.
  • Ответы с ошибками: $next возвращает ответ для любого HTTP-статуса. SDK выбрасывает свои типизированные исключения только после возврата всей цепочки, поэтому промежуточное ПО может проверить или заменить ответ 4xx или 5xx.
  • Исключения: исключение, выброшенное промежуточным ПО, доходит до вашего кода без изменений, за исключением двух случаев. SDK обрабатывает PSR-18 ClientExceptionInterface как ошибку подключения, которая проявляется как APIConnectionException. Он повторяет попытку после Anthropic\Core\Exceptions\RetryableException и выбрасывает это исключение без изменений, когда повторных попыток не осталось.
  • Аутентификация: SDK обновляет токены OAuth, а также подписывает или авторизует запросы Amazon Bedrock и Google Cloud внутри самого внутреннего $next. Поэтому запрос, изменённый вашим промежуточным ПО, подписывается после изменения и повторно при каждом вызове $next.
  • Тела ответов: промежуточное ПО, которое читает тело ответа, должно перемотать его или вернуть $response->withBody(...) с новым телом, чтобы SDK по-прежнему мог его декодировать. Потоковое тело невозможно перемотать, поэтому передавайте его дальше, не читая.

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

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

  • Claude Models on Google Cloud (Google managed): Anthropic\Vertex\Client. Используйте ::fromEnvironment().
  • Amazon Bedrock (bedrock-mantle): Anthropic\Bedrock\MantleClient. Используйте new MantleClient(awsRegion: ...).
  • Amazon Bedrock (bedrock-runtime): Anthropic\Bedrock\Client, для API InvokeModel. Используйте ::fromEnvironment() или ::withCredentials().
  • Claude Platform on AWS: Anthropic\Aws\Client (требует aws/aws-sdk-php в качестве необязательной зависимости). Используйте new Anthropic\Aws\Client(workspaceId: ...) или задайте ANTHROPIC_AWS_WORKSPACE_ID. Доступно в бета-версии.
  • Foundry: Anthropic\Foundry\Client. Используйте ::withCredentials().

PHP SDK также поддерживает Claude Models on Google Cloud (Anthropic managed) через Anthropic\GoogleCloud\Client. Этот клиент находится в стадии бета-тестирования. Anthropic\GoogleCloud\Client требует google/auth в качестве необязательной зависимости. Используйте new Anthropic\GoogleCloud\Client(workspaceId: ...) или задайте переменную окружения ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID. См. Определение проекта, расположения и рабочего пространства.

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

Этот пакет следует соглашениям SemVer.

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

Каждый запрос к Claude API использует определённую версию API. С этим SDK ваши запросы используют версию API, которая была актуальной на момент выпуска мажорной версии вашего SDK, поэтому вы переходите на новую версию API, обновляясь до новой мажорной версии. Версия 1.0.0 — первая, использующая 2026-10-21. Инструкции по обновлению см. в разделе Переход на версию API 2026-10-21.

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

Эта страница была полезной?