CLI、SDK 和库客户端 SDK

PHP SDK

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

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

PHP SDK 目前处于测试阶段。API 可能会在不同版本之间发生变化。

有关包含代码示例的 API 功能文档，请参阅 API 参考。本页面介绍 PHP 特定的 SDK 功能和配置。

安装

该 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-4-8',
);

echo $message->content[0]->text;

有关包括 Workload Identity Federation（工作负载身份联合）在内的身份验证选项，请参阅身份验证。

值对象

建议使用静态 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-4-8',
);

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

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

$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-4-8',
  );
} 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 请求超时、409 冲突、429 速率限制、>=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-4-8',
  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;
}

高级用法

未记录的属性

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

同名的 extra* 参数会覆盖已记录的参数。

<?php
// ...
use Anthropic\RequestOptions;
// ...
$message = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-4-8',
  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 支持以下平台：

Bedrock： Anthropic\Bedrock\MantleClient。使用 new MantleClient(awsRegion: ...)。
Bedrock（旧版）： Anthropic\Bedrock\Client。使用 ::fromEnvironment() 或 ::withCredentials()。
Vertex AI： Anthropic\Vertex\Client。使用 ::fromEnvironment()。
Foundry： Anthropic\Foundry\Client。使用 ::withCredentials()。
AWS 上的 Claude Platform： Anthropic\Aws\Client（需要 aws/aws-sdk-php 作为软依赖）。使用 new Anthropic\Aws\Client(workspaceId: ...) 或设置 ANTHROPIC_AWS_WORKSPACE_ID。目前处于测试阶段。

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

语义化版本控制

此包遵循 SemVer 约定。由于该库处于初始开发阶段且主版本号为 0，API 可能随时发生变化。

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

其他资源

Was this page helpful?

CLI、SDK 和库客户端 SDK

PHP SDK

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

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

PHP SDK 目前处于测试阶段。API 可能会在不同版本之间发生变化。

有关包含代码示例的 API 功能文档，请参阅 API 参考。本页面介绍 PHP 特定的 SDK 功能和配置。

安装

该 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-4-8',
);

echo $message->content[0]->text;

有关包括 Workload Identity Federation（工作负载身份联合）在内的身份验证选项，请参阅身份验证。

值对象

建议使用静态 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-4-8',
);

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

$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-4-8',
  );
} 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 请求超时、409 冲突、429 速率限制、>=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-4-8',
  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;
}

高级用法

未记录的属性

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

同名的 extra* 参数会覆盖已记录的参数。

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

未记录的请求参数

未记录的端点

要向未记录的端点发起请求，同时保留身份验证、重试和其他客户端功能的优势，您可以使用 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 支持以下平台：

Bedrock： Anthropic\Bedrock\MantleClient。使用 new MantleClient(awsRegion: ...)。
Bedrock（旧版）： Anthropic\Bedrock\Client。使用 ::fromEnvironment() 或 ::withCredentials()。
Vertex AI： Anthropic\Vertex\Client。使用 ::fromEnvironment()。
Foundry： Anthropic\Foundry\Client。使用 ::withCredentials()。
AWS 上的 Claude Platform： Anthropic\Aws\Client（需要 aws/aws-sdk-php 作为软依赖）。使用 new Anthropic\Aws\Client(workspaceId: ...) 或设置 ANTHROPIC_AWS_WORKSPACE_ID。目前处于测试阶段。

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

语义化版本控制

此包遵循 SemVer 约定。由于该库处于初始开发阶段且主版本号为 0，API 可能随时发生变化。

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

其他资源

Was this page helpful?