PHP SDK

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

Installation

Das SDK verwendet PSR-18 für HTTP und erkennt jeden installierten PSR-18-Client automatisch. Guzzle wird empfohlen, da das SDK ihn 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 Namen gesetzt werden.

$client = new Client();

$message = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-4-8',
);

echo $message->content[0]->text;

Für Authentifizierungsoptionen einschließlich Workload Identity Federation siehe Authentifizierung.

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 bietet Unterstützung für Streaming-Antworten mittels „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-4-8',
);

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

Streaming erfordert einen HTTP-Client, der den Response-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, sobald die Antwort abgeschlossen ist, statt inkrementell; wenn du dieses Symptom beobachtest, installiere Guzzle oder stelle einen Streaming-fähigen PSR-18-Client über die Request-Option streamingTransporter bereit:

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

Fehlerbehandlung

Wenn die Bibliothek keine Verbindung zur API herstellen kann oder wenn die API einen Nicht-Erfolgs-Statuscode zurückgibt (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-4-8',
  );
} 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 Rate Limit, >=500 Internal-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 Standard 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-4-8',
  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);

// Rufe Elemente von der aktuellen Seite ab
foreach ($page->getItems() as $item) {
  echo $item->id, PHP_EOL;
}
// Führe zusätzliche Netzwerkanfragen aus, um Elemente von allen Seiten ab der aktuellen abzurufen
foreach ($page->pagingEachItem() as $item) {
  echo $item->id, PHP_EOL;
}

Erweiterte Verwendung

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-4-8',
  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 mit den Optionen extraQueryParams, extraBodyParams und extraHeaders unter RequestOptions::with() beim Erstellen einer Anfrage tun, wie im vorherigen Beispiel gezeigt.

Undokumentierte Endpunkte

Um Anfragen an undokumentierte Endpunkte zu stellen und dabei die Vorteile von Authentifizierung, Wiederholungsversuchen und anderen Client-Funktionen zu behalten, 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:

• Bedrock: Anthropic\Bedrock\MantleClient. Verwende new MantleClient(awsRegion: ...).
• Bedrock (Legacy): Anthropic\Bedrock\Client. Verwende ::fromEnvironment() oder ::withCredentials().
• Vertex AI: Anthropic\Vertex\Client. Verwende ::fromEnvironment().
• Foundry: Anthropic\Foundry\Client. Verwende ::withCredentials().
• Claude Platform auf AWS: Anthropic\Aws\Client (erfordert aws/aws-sdk-php als Soft-Dependency). Verwende new Anthropic\Aws\Client(workspaceId: ...) oder setze ANTHROPIC_AWS_WORKSPACE_ID. Verfügbar in der Beta.

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 eine Hauptversion von 0 hat, können sich APIs jederzeit ändern.

Dieses Paket betrachtet Verbesserungen an den (Nicht-Laufzeit-)PHPDoc-Typdefinitionen als nicht-breaking Änderungen.

Zusätzliche Ressourcen

• GitHub-Repository
• Packagist
• API-Referenz
• Streaming Messages