PHP SDK
값 객체와 빌더 패턴을 지원하는 Anthropic PHP SDK를 설치하고 구성합니다
Anthropic PHP 라이브러리는 PHP 8.1.0 이상의 모든 애플리케이션에서 Claude API에 편리하게 접근할 수 있도록 해 줍니다.
설치
SDK는 HTTP에 PSR-18을 사용하며, 설치된 PSR-18 클라이언트를 자동으로 탐색합니다. SDK가 추가 설정 없이 “streaming”(스트리밍)용으로 구성해 주므로 Guzzle을 권장합니다:
composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7"요구 사항
PHP 8.1.0 이상.
사용법
이 라이브러리는 선택적 인수를 지정하기 위해 “named parameter”(명명된 매개변수)를 사용합니다. 기본값이 있는 매개변수는 이름으로 설정해야 합니다.
$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').
스트리밍
SDK는 “Server-Sent Events”(서버 전송 이벤트), 즉 SSE를 사용한 스트리밍 응답을 지원합니다.
$client = new Client();
$stream = $client->messages->createStream(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Hello, Claude']],
model: Model::CLAUDE_OPUS_5_5,
);
foreach ($stream as $event) {
echo $event->type . PHP_EOL;
}스트리밍에는 응답 본문을 점진적으로 반환하는 HTTP 클라이언트가 필요합니다. Guzzle이 탐색된 PSR-18 클라이언트인 경우 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;
use Anthropic\Messages\Model;
try {
$message = $client->messages->create(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Hello, Claude']],
model: 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 옵션을 사용하여 이를 구성하거나 비활성화할 수 있습니다:
use Anthropic\Messages\Model;
use Anthropic\RequestOptions;
// 모든 요청에 대한 기본값을 구성합니다:
$client = new Client(requestOptions: RequestOptions::with(maxRetries: 0));
// 또는 요청별로 구성합니다:
$result = $client->messages->create(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Hello, Claude']],
model: Model::CLAUDE_OPUS_5_5,
requestOptions: RequestOptions::with(maxRetries: 5),
);페이지네이션
Claude API의 목록 메서드는 “pagination”(페이지네이션)을 사용합니다.
이 라이브러리는 각 목록 응답에 자동 페이지네이션 이터레이터를 제공하므로 후속 페이지를 수동으로 요청할 필요가 없습니다:
$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는 전송하는 각 요청에 대해 스팬을 내보냅니다. 스팬을 관측성 플랫폼으로 전송하려면 Anthropic 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']
);미들웨어
“Middleware”(미들웨어)는 클라이언트가 보내는 모든 HTTP 요청 전후에 코드를 실행합니다. SDK 미들웨어에서 미들웨어를 등록하는 방법과 여러 미들웨어가 실행되는 순서를 설명합니다. 이 섹션에서는 PHP SDK에 해당하는 세부 사항을 다룹니다.
미들웨어는 요청과 $next를 받는 callable이거나, Anthropic\Middleware를 구현하는 클래스의 인스턴스이며, 그 handle() 메서드는 동일한 시그니처를 가집니다. middleware 요청 옵션은 둘 다 허용합니다:
use Anthropic\Middleware;
use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;
final class TracingMiddleware implements Middleware
{
public function handle(RequestInterface $request, \Closure $next): ResponseInterface
{
return $next($request->withHeader('x-trace-id', bin2hex(random_bytes(8))));
}
}
$client = new Client(requestOptions: ['middleware' => [new TracingMiddleware()]]);$next는 체인의 나머지를 실행하고 요청을 보냅니다. 요청을 전달하려면 한 번 호출하고, 자체 응답(예: 캐시된 응답)을 반환하려면 호출을 건너뛰며, 후속 요청(예: 사용자 정의 재시도)을 보내려면 여러 번 호출하세요.
SDK는 또한 모든 미들웨어에 세 번째 인수로 요청의 Anthropic\RequestOptions를 전달하며, 이는 클라이언트의 옵션과 호출의 옵션을 병합한 것입니다. fallbackState와 같은 옵션을 읽으려면 선택적 세 번째 매개변수 ?RequestOptions $options = null을 선언하세요. 모든 미들웨어와 요청의 모든 재시도가 이 객체를 공유하므로 읽기 전용으로 취급하세요. callable에 이미 다른 용도의 세 번째 매개변수가 있다면, SDK가 모든 호출에서 해당 매개변수를 채우므로 이를 다시 작성하세요.
런타임 동작:
- 재시도: 미들웨어는 SDK의 재시도 루프 내부에서 각 HTTP 시도마다 한 번씩 실행되므로, 재시도할 때마다 다시 실행됩니다.
- 오류 응답:
$next는 모든 HTTP 상태에 대해 응답을 반환합니다. SDK는 전체 체인이 반환된 후에만 타입이 지정된 예외를 발생시키므로, 미들웨어는 4xx 또는 5xx 응답을 검사하거나 대체할 수 있습니다. - 예외: 미들웨어가 발생시킨 예외는 두 가지 경우를 제외하고 변경 없이 코드에 전달됩니다. SDK는 PSR-18
ClientExceptionInterface를 연결 오류로 처리하며, 이는APIConnectionException으로 나타납니다. 또한Anthropic\Core\Exceptions\RetryableException이후에는 해당 시도를 재시도하며, 남은 재시도가 없으면 해당 예외를 변경 없이 발생시킵니다. - 인증: SDK는 가장 안쪽의
$next내부에서 OAuth 토큰을 갱신하고, Amazon Bedrock 및 Google Cloud 요청에 서명하거나 권한을 부여합니다. 따라서 미들웨어가 변경한 요청은 변경 후에 서명되며,$next를 호출할 때마다 다시 서명됩니다. - 응답 본문: 응답 본문을 읽는 미들웨어는 SDK가 여전히 디코딩할 수 있도록 본문을 되감거나, 새 본문과 함께
$response->withBody(...)를 반환해야 합니다. 스트리밍 본문은 되감을 수 없으므로 읽지 않은 상태로 그대로 전달하세요.
플랫폼 통합
PHP SDK는 다음 플랫폼을 지원합니다:
- Claude Models on Google Cloud (Google managed):
Anthropic\Vertex\Client.::fromEnvironment()를 사용하세요. - Amazon Bedrock (
bedrock-mantle):Anthropic\Bedrock\MantleClient.new MantleClient(awsRegion: ...)를 사용하세요. - Amazon Bedrock (
bedrock-runtime):InvokeModelAPI용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()를 사용하세요.
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 환경 변수를 설정하세요. 프로젝트, 위치 및 워크스페이스 확인을 참조하세요.
시맨틱 버전 관리
이 패키지는 SemVer 규칙을 따릅니다.
이 패키지는 (런타임이 아닌) PHPDoc 타입 정의의 개선을 호환성을 깨지 않는 변경으로 간주합니다.
Claude API에 대한 모든 요청은 API 버전을 사용합니다. 이 SDK를 사용하면 요청은 SDK의 메이저 버전이 릴리스될 당시의 최신 API 버전을 사용하므로, 새 메이저 버전으로 업그레이드하여 새 API 버전으로 전환합니다. 버전 1.0.0은 2026-10-21을 사용하는 첫 번째 버전입니다. 업그레이드 방법은 API 버전 2026-10-21로 마이그레이션을 참조하세요.
추가 리소스
이 페이지가 도움이 되었나요?