---
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>
  코드 예제가 포함된 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가 추가 설정 없이 "streaming"(스트리밍)용으로 구성해 주므로 [Guzzle](https://docs.guzzlephp.org/)을 권장합니다:

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

## 요구 사항

PHP 8.1.0 이상.

## 사용법

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

```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를 사용한 스트리밍 응답을 지원합니다.

```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 클라이언트가 필요합니다. Guzzle이 탐색된 PSR-18 클라이언트인 경우 SDK가 자동으로 스트리밍용으로 구성합니다. 버퍼링 클라이언트를 사용하면 `foreach` 루프가 이벤트를 점진적으로 내보내는 대신 응답이 완료될 때 모든 이벤트를 한꺼번에 내보냅니다. 이러한 증상이 나타나면 Guzzle을 설치하거나 `streamingTransporter` 요청 옵션을 통해 스트리밍을 지원하는 PSR-18 클라이언트를 제공하세요:

```php
$client = new Client(
  requestOptions: 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`       |

## 재시도

특정 오류는 기본적으로 짧은 "exponential backoff"(지수 백오프)와 함께 자동으로 두 번 재시도됩니다.

연결 오류(예: 네트워크 연결 문제로 인한 오류), 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의 목록 메서드는 "pagination"(페이지네이션)을 사용합니다.

이 라이브러리는 각 목록 응답에 자동 페이지네이션 이터레이터를 제공하므로 후속 페이지를 수동으로 요청할 필요가 없습니다:

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

## 고급 사용법

### OpenTelemetry 추적

애플리케이션이 OpenTelemetry 트레이서 프로바이더를 등록하면 SDK는 전송하는 각 요청에 대해 스팬을 내보냅니다. 스팬을 관측성 플랫폼으로 전송하려면 [Claude SDK에서 OpenTelemetry 설정하기](https://platform.claude.com/docs/ko/manage-claude/opentelemetry/sdk)를 참조하세요.

### 문서화되지 않은 속성

다음과 같이 모든 엔드포인트에 문서화되지 않은 매개변수를 보내고, 문서화되지 않은 응답 속성을 읽을 수 있습니다:

<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)
  * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/google-managed)
  * [Microsoft Foundry](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry)

  [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/anthropic-managed)도 참조하세요.
</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를 사용하는 기존 애플리케이션을 위해 유지됩니다.

PHP SDK는 `Anthropic\GoogleCloud\Client`를 통해 Claude Models on Google Cloud (Anthropic managed)도 지원합니다. 이 클라이언트는 베타 버전입니다. `Anthropic\GoogleCloud\Client`는 `google/auth`를 "soft dependency"(선택적 의존성)로 필요로 합니다. `new Anthropic\GoogleCloud\Client(workspaceId: ...)`를 사용하거나 `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID` 환경 변수를 설정하세요. [프로젝트, 위치 및 워크스페이스 확인](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution)을 참조하세요.

## 시맨틱 버전 관리

이 SDK의 각 메이저 버전은 기본적으로 `anthropic-version` 헤더에 하나의 API 버전을 보내며, 새로운 API 버전마다 새로운 메이저 버전이 함께 출시됩니다. `2026-10-21`을 보내는 첫 번째 메이저 버전은 1.0.0입니다. [2026-10-21로 업그레이드](https://platform.claude.com/docs/ko/api/migration-2026-10-21#upgrade)를 참조하세요.

이 패키지는 [SemVer](https://semver.org/spec/v2.0.0.html) 규칙을 따릅니다.

이 패키지는 (런타임이 아닌) 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)