---
title: PHP SDK
url: https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/php
description: 값 객체와 빌더 패턴을 사용하여 Anthropic PHP SDK를 설치하고 구성합니다
---

Anthropic PHP 라이브러리는 모든 PHP 8.1.0+ 애플리케이션에서 Claude API에 편리하게 접근할 수 있도록 합니다.

<Info>
  PHP SDK는 현재 베타 버전입니다. API는 버전 간에 변경될 수 있습니다.
</Info>

<Info>
  코드 예제가 포함된 API 기능 문서는 [API 레퍼런스](https://platform.claude.com/docs/ko/api/overview)를 참조하세요. 이 페이지는 PHP 전용 SDK 기능과 구성을 다룹니다.
</Info>

## 설치

SDK는 HTTP에 [PSR-18](https://www.php-fig.org/psr/psr-18/)을 사용하며, 설치된 PSR-18 클라이언트를 자동으로 검색합니다. SDK가 추가 설정 없이 스트리밍용으로 구성해 주므로 [Guzzle](https://docs.guzzlephp.org/)을 권장합니다:

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

## 요구 사항

PHP 8.1.0 이상.

## 사용법

이 라이브러리는 선택적 인수를 지정하기 위해 명명된 매개변수(named parameters)를 사용합니다. 기본값이 있는 매개변수는 이름으로 설정해야 합니다.

```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/ko/manage-claude/authentication)을 참조하세요. API 키가 여러 워크스페이스에 액세스할 수 있는 [개인 또는 서비스 계정 키](https://platform.claude.com/docs/ko/manage-claude/authentication#key-types)인 경우, `anthropic-workspace-id` 요청 헤더에 워크스페이스 ID를 설정하세요. [워크스페이스 선택](https://platform.claude.com/docs/ko/manage-claude/authentication#select-a-workspace)에서 이 SDK에 대한 요청별 옵션을 확인할 수 있습니다.

## 값 객체

값 객체를 초기화할 때는 정적 `with` 생성자 `Base64ImageSource::with(data: "U3RhaW5sZXNzIHJvY2tz", ...)`와 명명된 매개변수를 사용하는 것을 권장합니다.

그러나 빌더도 제공됩니다: `(new Base64ImageSource)->withData("U3RhaW5sZXNzIHJvY2tz")`.

## 스트리밍

SDK는 Server-Sent Events(SSE)를 사용한 "streaming"(스트리밍) 응답을 지원합니다.

```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`의 하위 클래스가 throw됩니다:

```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 Internal 오류 및 타임아웃은 모두 기본적으로 재시도됩니다.

`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/ko/build-with-claude/claude-in-amazon-bedrock)
  * [Amazon Bedrock (Opus 4.6 및 이전 버전)](https://platform.claude.com/docs/ko/build-with-claude/claude-on-amazon-bedrock-legacy)
  * [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws)
  * [Google Cloud](https://platform.claude.com/docs/ko/build-with-claude/claude-on-vertex-ai)
  * [Microsoft Foundry](https://platform.claude.com/docs/ko/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`를 설정하세요. 베타로 제공됩니다.
* **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/ko/api/overview)
* [메시지 스트리밍](https://platform.claude.com/docs/ko/build-with-claude/streaming)