PHP SDK

安装和配置 Anthropic PHP SDK，使用值对象和构建器模式

Anthropic PHP 库为任何 PHP 8.1.0+ 应用程序提供了便捷访问 Claude API 的方式。

安装

该 SDK 使用 PSR-18 处理 HTTP，并会自动发现任何已安装的 PSR-18 客户端。推荐使用 Guzzle，因为 SDK 会自动将其配置为支持流式传输，无需额外设置：

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 请求标头中设置工作区 ID；选择工作区介绍了此 SDK 的按请求设置选项。

值对象

建议使用静态 with 构造函数 Base64ImageSource::with(data: "U3RhaW5sZXNzIHJvY2tz", ...) 和命名参数来初始化值对象。

不过，也提供了构建器 (new Base64ImageSource)->withData("U3RhaW5sZXNzIHJvY2tz")。

流式传输

"Streaming"（流式传输）：SDK 支持使用 "Server-Sent Events"（服务器发送事件），即 SSE，来流式传输响应。

$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;
}

流式传输需要一个能够增量返回响应体的 HTTP 客户端。当发现的 PSR-18 客户端是 Guzzle 时，SDK 会自动将其配置为支持流式传输。如果使用缓冲型客户端，foreach 循环会在响应完成时一次性产出所有事件，而不是增量产出；如果您观察到这种现象，请安装 Guzzle，或通过 streamingTransporter 请求选项提供一个支持流式传输的 PSR-18 客户端：

$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;
// ...
try {
  $message = $client->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();
}

错误代码如下：

原因	错误类型
HTTP 400	`BadRequestException`
HTTP 401	`AuthenticationException`
HTTP 403	`PermissionDeniedException`
HTTP 404	`NotFoundException`
HTTP 409	`ConflictException`
HTTP 422	`UnprocessableEntityException`
HTTP 429	`RateLimitException`
HTTP >= 500	`InternalServerException`
其他 HTTP 错误	`APIStatusException`
超时	`APITimeoutException`
网络错误	`APIConnectionException`

重试

默认情况下，某些错误会自动重试两次，并采用短暂的指数退避。

连接错误（例如由于网络连接问题）、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-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 tracer provider 时，SDK 会为其发送的每个请求发出一个 span。要将这些 span 发送到您的可观测性平台，请参阅在 Claude SDK 中设置 OpenTelemetry。

未记录的属性

您可以向任何端点发送未记录的参数，并读取未记录的响应属性，如下所示：

<?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'],
  ),
);

未记录的请求参数

如果您想显式发送额外参数，可以在发出请求时使用 RequestOptions::with() 下的 extraQueryParams、extraBodyParams 和 extraHeaders 选项，如前面的示例所示。

未记录的端点

要向未记录的端点发出请求，同时保留身份验证、重试和其他客户端功能的优势，您可以使用 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 on AWS： Anthropic\Aws\Client（需要 aws/aws-sdk-php 作为软依赖）。使用 new Anthropic\Aws\Client(workspaceId: ...) 或设置 ANTHROPIC_AWS_WORKSPACE_ID。以 beta 形式提供。
Foundry： Anthropic\Foundry\Client。使用 ::withCredentials()。

新项目请使用 MantleClient；Anthropic\Bedrock\Client 保留用于使用 Bedrock InvokeModel API 的现有应用程序。

PHP SDK 还通过 Anthropic\GoogleCloud\Client 支持 Claude Models on Google Cloud (Anthropic managed)。此客户端目前处于 beta 阶段。Anthropic\GoogleCloud\Client 需要 google/auth 作为软依赖（soft dependency）。请使用 new Anthropic\GoogleCloud\Client(workspaceId: ...) 或设置 ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID 环境变量。请参阅项目、位置和工作区解析。

语义化版本

此 SDK 的每个主版本默认在 anthropic-version 标头中发送一个 API 版本，并且每个新的 API 版本都会伴随一个新的主版本。第一个发送 2026-10-21 的主版本是 1.0.0；请参阅升级到 2026-10-21。

此软件包遵循 SemVer 约定。

此软件包将对（非运行时）PHPDoc 类型定义的改进视为非破坏性变更。

安装

要求

用法

值对象

流式传输

错误处理

重试

分页

高级用法

OpenTelemetry 追踪

未记录的属性

未记录的请求参数

未记录的端点

平台集成

语义化版本

其他资源

安装

要求

用法

值对象