PHP SDK

Die Anthropic-PHP-Bibliothek bietet bequemen Zugriff auf die Claude API aus jeder Anwendung mit PHP 8.1.0+.

Installation

Das SDK verwendet PSR-18 für HTTP und erkennt jeden installierten PSR-18-Client automatisch. Guzzle wird empfohlen, da das SDK es ohne zusätzliche Einrichtung für Streaming konfiguriert:

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

Anforderungen

PHP 8.1.0 oder höher.

Verwendung

Diese Bibliothek verwendet benannte Parameter, um optionale Argumente anzugeben. Parameter mit einem Standardwert müssen per Name gesetzt werden.

$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;

Authentifizierungsoptionen einschließlich Workload Identity Federation findest du unter Authentifizierung. Wenn dein API-Key ein persönlicher Key oder ein Service-Account-Key mit Zugriff auf mehrere Workspaces ist, setze die Workspace-ID im Request-Header anthropic-workspace-id; Einen Workspace auswählen zeigt die Option pro Anfrage für dieses SDK.

Value Objects

Es wird empfohlen, den statischen with-Konstruktor Base64ImageSource::with(data: "U3RhaW5sZXNzIHJvY2tz", ...) und benannte Parameter zu verwenden, um „value objects“ (Wertobjekte) zu initialisieren.

Es werden jedoch auch Builder bereitgestellt: (new Base64ImageSource)->withData("U3RhaW5sZXNzIHJvY2tz").

Streaming

Das SDK unterstützt Streaming-Antworten mithilfe von „Server-Sent Events“ (vom Server gesendete Ereignisse), oder SSE.

$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;
}

Streaming erfordert einen HTTP-Client, der den Antwort-Body inkrementell zurückgibt. Wenn Guzzle der erkannte PSR-18-Client ist, konfiguriert das SDK ihn automatisch für Streaming. Bei einem puffernden Client liefert die foreach-Schleife alle Events auf einmal, wenn die Antwort abgeschlossen ist, statt inkrementell; wenn du dieses Symptom beobachtest, installiere Guzzle oder stelle über die Request-Option streamingTransporter einen Streaming-fähigen PSR-18-Client bereit:

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

Fehlerbehandlung

Wenn die Bibliothek keine Verbindung zur API herstellen kann oder die API einen nicht erfolgreichen Statuscode zurückgibt (das heißt eine 4xx- oder 5xx-Antwort), wird eine Unterklasse von Anthropic\Core\Exceptions\APIException geworfen:

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

Die Fehlercodes sind wie folgt:

Wiederholungsversuche

Bestimmte Fehler werden standardmäßig automatisch zweimal wiederholt, mit einem kurzen exponentiellen Backoff.

Verbindungsfehler (zum Beispiel aufgrund eines Netzwerkverbindungsproblems), 408 Request Timeout, 409 Conflict, 429 Ratenlimit, interne Fehler >=500 sowie Timeouts werden standardmäßig alle wiederholt.

Du kannst die Option maxRetries verwenden, um dies zu konfigurieren oder zu deaktivieren:

use Anthropic\RequestOptions;
// ...
// Konfiguriere den Standardwert für alle Anfragen:
$client = new Client(requestOptions: RequestOptions::with(maxRetries: 0));

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

Paginierung

List-Methoden in der Claude API sind paginiert.

Diese Bibliothek stellt mit jeder List-Antwort automatisch paginierende Iteratoren bereit, sodass du aufeinanderfolgende Seiten nicht manuell anfordern musst:

$client = new Client();

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

// Elemente der aktuellen Seite abrufen
foreach ($page->getItems() as $item) {
  echo $item->id, PHP_EOL;
}
// zusätzliche Netzwerkanfragen stellen, um Elemente aller Seiten abzurufen, einschließlich der aktuellen Seite und aller folgenden
foreach ($page->pagingEachItem() as $item) {
  echo $item->id, PHP_EOL;
}

Erweiterte Verwendung

Undokumentierte Eigenschaften

Du kannst undokumentierte Parameter an jeden Endpunkt senden und undokumentierte Antwort-Eigenschaften wie folgt lesen:

<?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'],
  ),
);

Undokumentierte Request-Parameter

Wenn du explizit einen zusätzlichen Parameter senden möchtest, kannst du dies beim Stellen einer Anfrage mit den Optionen extraQueryParams, extraBodyParams und extraHeaders unter RequestOptions::with() tun, wie im vorangehenden Beispiel gezeigt.

Undokumentierte Endpunkte

Um Anfragen an undokumentierte Endpunkte zu stellen und dabei die Vorteile von Authentifizierung, Wiederholungsversuchen und anderen Client-Funktionen beizubehalten, kannst du Anfragen mit client->request wie folgt stellen:

$client = new Client();

$response = $client->request(
  method: "post",
  path: '/undocumented/endpoint',
  query: ['dog' => 'woof'],
  headers: ['useful-header' => 'interesting-value'],
  body: ['hello' => 'world']
);

Plattform-Integrationen

Das PHP SDK unterstützt die folgenden Plattformen:

• Agent Platform: Anthropic\Vertex\Client. Verwende ::fromEnvironment().
• Bedrock: Anthropic\Bedrock\MantleClient. Verwende new MantleClient(awsRegion: ...).
• Bedrock (veraltet): Anthropic\Bedrock\Client. Verwende ::fromEnvironment() oder ::withCredentials().
• Claude Platform on AWS: Anthropic\Aws\Client (erfordert aws/aws-sdk-php als weiche Abhängigkeit). Verwende new Anthropic\Aws\Client(workspaceId: ...) oder setze ANTHROPIC_AWS_WORKSPACE_ID. In der Beta-Phase verfügbar.
• Foundry: Anthropic\Foundry\Client. Verwende ::withCredentials().

Verwende MantleClient für neue Projekte; Anthropic\Bedrock\Client bleibt für bestehende Anwendungen erhalten, die die Bedrock-InvokeModel-API verwenden.

Semantische Versionierung

Dieses Paket folgt den SemVer-Konventionen. Da sich die Bibliothek in der anfänglichen Entwicklung befindet und die Hauptversion 0 hat, können sich APIs jederzeit ändern.

Dieses Paket betrachtet Verbesserungen an den (nicht zur Laufzeit wirksamen) PHPDoc-Typdefinitionen als nicht-brechende Änderungen.

Zusätzliche Ressourcen

• GitHub-Repository
• Packagist
• API-Referenz
• Streaming von Nachrichten