PHP SDK

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 이상.

사용법

이 라이브러리는 네임드 파라미터로 선택적 인자를 지정해요. 기본값이 있는 파라미터는 이름으로 설정해야 해요.

$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: 'claude-opus-5-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의 하위 클래스가 발생해요:

<?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();
}

오류 코드는 다음과 같아요:

재시도

일부 오류는 기본적으로 짧은 지수 백오프로 두 번 자동 재시도돼요.

연결 오류(예: 네트워크 연결 문제), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 내부 오류, 타임아웃은 모두 기본적으로 재시도돼요.

maxRetries 옵션으로 설정하거나 끌 수 있어요:

use Anthropic\RequestOptions;
// ...
// Configure the default for all requests:
$client = new Client(requestOptions: RequestOptions::with(maxRetries: 0));

// Or, configure per-request:
$result = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-5-5',
  requestOptions: RequestOptions::with(maxRetries: 5),
);

페이징

Claude API의 목록 메서드는 페이징돼요.

이 라이브러리는 각 목록 응답과 함께 자동 페이징 반복자를 제공하므로, 연속 페이지를 수동으로 요청할 필요가 없어요:

$client = new Client();

$page = $client->beta->messages->batches->list(limit: 20);

// fetch items from the current page
foreach ($page->getItems() as $item) {
  echo $item->id, PHP_EOL;
}
// make additional network requests to fetch items from all pages, including and after the current page
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-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']
);

플랫폼 통합