Claude Platform Docs
CLI, SDK 및 라이브러리클라이언트 SDK

PHP SDK

값 객체와 빌더 패턴을 사용하여 Anthropic PHP SDK를 설치하고 구성합니다

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

설치

SDK는 HTTP에 PSR-18을 사용하며, 설치된 PSR-18 클라이언트를 자동으로 검색합니다. SDK가 추가 설정 없이 스트리밍용으로 구성해 주므로 Guzzle을 권장합니다:

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

요구 사항

PHP 8.1.0 이상.

사용법

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

$client = new Client();

$message = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-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)를 사용한 "streaming"(스트리밍) 응답을 지원합니다.

$client = new Client();

$stream = $client->messages->createStream(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-5',
);

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

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

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

오류 처리

라이브러리가 API에 연결할 수 없거나 API가 성공이 아닌 상태 코드(즉, 4xx 또는 5xx 응답)를 반환하면 Anthropic\Core\Exceptions\APIException의 하위 클래스가 throw됩니다:

<?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',
  );
} 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 400BadRequestException
HTTP 401AuthenticationException
HTTP 403PermissionDeniedException
HTTP 404NotFoundException
HTTP 409ConflictException
HTTP 422UnprocessableEntityException
HTTP 429RateLimitException
HTTP >= 500InternalServerException
기타 HTTP 오류APIStatusException
타임아웃APITimeoutException
네트워크 오류APIConnectionException

재시도

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

연결 오류(예: 네트워크 연결 문제로 인한 오류), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal 오류 및 타임아웃은 모두 기본적으로 재시도됩니다.

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-5',
  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;
}

고급 사용법

문서화되지 않은 속성

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

<?php

use Anthropic\RequestOptions;

$message = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-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']
);

플랫폼 통합

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 규칙을 따릅니다. 라이브러리가 초기 개발 단계에 있고 메이저 버전이 0이므로 API는 언제든지 변경될 수 있습니다.

이 패키지는 (런타임이 아닌) PHPDoc 타입 정의의 개선을 호환성을 깨지 않는 변경으로 간주합니다.

추가 리소스

Was this page helpful?