---
title: PHP SDK
url: https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/sdks/php
description: 安裝並設定 Anthropic PHP SDK，使用值物件與建構器模式
---

Anthropic PHP 函式庫讓任何 PHP 8.1.0+ 應用程式都能便利地存取 Claude API。

<Info>
  PHP SDK 目前處於 beta 階段。API 可能會在不同版本之間有所變動。
</Info>

<Info>
  如需附有程式碼範例的 API 功能文件，請參閱 [API 參考文件](https://platform.claude.com/docs/zh-TW/api/overview)。本頁涵蓋 PHP 專屬的 SDK 功能與設定。
</Info>

## 安裝

此 SDK 使用 [PSR-18](https://www.php-fig.org/psr/psr-18/) 進行 HTTP 通訊，並會自動偵測任何已安裝的 PSR-18 用戶端。建議使用 [Guzzle](https://docs.guzzlephp.org/)，因為 SDK 會自動將其設定為支援「streaming」（串流），無需額外設定：

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

## 需求

PHP 8.1.0 或更高版本。

## 使用方式

此函式庫使用具名參數來指定選用引數。具有預設值的參數必須以名稱設定。

```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;
```

如需了解包括 Workload Identity Federation（工作負載身分聯合）在內的驗證選項，請參閱[驗證](https://platform.claude.com/docs/zh-TW/manage-claude/authentication)。如果您的 API 金鑰是可存取多個工作區的[個人或服務帳戶金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#key-types)，請在 `anthropic-workspace-id` 請求標頭中設定工作區 ID；[選擇工作區](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#select-a-workspace)說明了此 SDK 的逐請求選項。

## 值物件

建議使用靜態 `with` 建構子 `Base64ImageSource::with(data: "U3RhaW5sZXNzIHJvY2tz", ...)` 搭配具名參數來初始化「value objects」（值物件）。

不過，也提供了建構器 `(new Base64ImageSource)->withData("U3RhaW5sZXNzIHJvY2tz")`。

## 串流

此 SDK 支援使用「Server-Sent Events」（伺服器傳送事件），即 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;
}
```

串流需要能夠以遞增方式回傳回應主體的 HTTP 用戶端。當偵測到的 PSR-18 用戶端為 Guzzle 時，SDK 會自動將其設定為支援串流。若使用會緩衝的用戶端，`foreach` 迴圈會在回應完成時一次產出所有事件，而非遞增產出；如果您觀察到此現象，請安裝 Guzzle，或透過 `streamingTransporter` 請求選項提供支援串流的 PSR-18 用戶端：

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

## 錯誤處理

當函式庫無法連線至 API，或 API 回傳非成功狀態碼（亦即 4xx 或 5xx 回應）時，會拋出 `Anthropic\Core\Exceptions\APIException` 的子類別：

```php
<?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` 選項來設定或停用此行為：

```php
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 中的列表方法皆採分頁方式。

此函式庫為每個列表回應提供自動分頁的迭代器，因此您無需手動請求後續頁面：

```php
$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;
// ...
}
```

## 進階用法

### 未記載的屬性

您可以向任何端點傳送未記載的參數，並讀取未記載的回應屬性，方式如下：

<Note>
  同名的 `extra*` 參數會覆寫已記載的參數。
</Note>

```php
<?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` 發出請求，方式如下：

```php
$client = new Client();

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

## 平台整合

<Note>
  如需附有程式碼範例的詳細平台設定指南，請參閱：

  * [Amazon Bedrock](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-amazon-bedrock)
  * [Amazon Bedrock（Opus 4.6 及更早版本）](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-on-amazon-bedrock-legacy)
  * [Claude Platform on AWS](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws)
  * [Google Cloud](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-on-vertex-ai)
  * [Microsoft Foundry](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-microsoft-foundry)
</Note>

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 的既有應用程式。

## 語意化版本

此套件遵循 [SemVer](https://semver.org/spec/v2.0.0.html) 慣例。由於此函式庫仍處於初期開發階段且主版本號為 `0`，API 可能隨時變動。

此套件將（非執行期的）PHPDoc 型別定義的改進視為非破壞性變更。

## 其他資源

* [GitHub 儲存庫](https://github.com/anthropics/anthropic-sdk-php)
* [Packagist](https://packagist.org/packages/anthropic-ai/sdk)
* [API 參考文件](https://platform.claude.com/docs/zh-TW/api/overview)
* [串流訊息](https://platform.claude.com/docs/zh-TW/build-with-claude/streaming)