PHP SDK

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

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

$textBlock = array_find($message->content, static fn ($block): bool => $block->type === 'text');
echo $textBlock->text;

Informationen zu Authentifizierungsoptionen, einschließlich Workload Identity Federation, findest du unter Authentifizierung. Wenn dein API-Key ein persönlicher Key oder Service-Account-Key ist, der nicht auf einen Workspace beschränkt 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 zu initialisieren.

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

Streaming

Das SDK unterstützt „streaming" (Streaming) von Antworten mithilfe von 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;
}

Streaming erfordert einen HTTP-Client, der den Antworttext 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 streamingfähigen PSR-18-Client bereit:

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

Fehlerbehandlung

Wenn die Bibliothek keine Verbindung zur API herstellen kann oder die API einen Statuscode zurückgibt, der keinen Erfolg anzeigt (also eine 4xx- oder 5xx-Antwort), wird eine Unterklasse von Anthropic\Core\Exceptions\APIException ausgelöst:

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

Die Fehlercodes lauten 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 Rate Limit, >=500 interne Fehler und 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 es pro Anfrage:
$result = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-5-5',
  requestOptions: RequestOptions::with(maxRetries: 5),
);

Paginierung

Listenmethoden in der Claude API sind paginiert.

Diese Bibliothek stellt mit jeder Listenantwort 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 ab der aktuellen Seite abzurufen
// ...
foreach ($page->pagingEachItem() as $item) {
  echo $item->id, PHP_EOL;
// ...
}

Erweiterte Verwendung

OpenTelemetry-Tracing

Wenn deine Anwendung einen OpenTelemetry Tracer Provider registriert, gibt das SDK für jede Anfrage, die es sendet, einen Span aus. Um die Spans an deine Observability-Plattform zu senden, siehe OpenTelemetry mit dem Claude SDK einrichten.

Undokumentierte Eigenschaften

Du kannst undokumentierte Parameter an jeden Endpunkt senden und undokumentierte Antworteigenschaften wie folgt lesen:

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

Undokumentierte Request-Parameter

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

Undokumentierte Endpunkte

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

$client = new Client();

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

Plattformintegrationen

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 optionale Abhängigkeit). Verwende new Anthropic\Aws\Client(workspaceId: ...) oder setze ANTHROPIC_AWS_WORKSPACE_ID. In der Beta 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.

Das PHP SDK unterstützt über Anthropic\GoogleCloud\Client auch Claude Models on Google Cloud (Anthropic managed). Dieser Client befindet sich in der Beta-Phase. Anthropic\GoogleCloud\Client benötigt google/auth als optionale Abhängigkeit („soft dependency"). Verwende new Anthropic\GoogleCloud\Client(workspaceId: ...) oder setze die Umgebungsvariable ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID. Siehe Auflösung von Projekt, Standort und Workspace.

Semantische Versionierung

Jede Hauptversion dieses SDK sendet standardmäßig eine API-Version im anthropic-version-Header, und mit jeder neuen API-Version kommt eine neue Hauptversion. Die erste Hauptversion, die 2026-10-21 sendet, ist 1.0.0; siehe Upgrade auf 2026-10-21.

Dieses Paket folgt den SemVer-Konventionen.

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

Zusätzliche Ressourcen

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