PHP SDK

La libreria PHP di Anthropic fornisce un accesso comodo alla Claude API da qualsiasi applicazione PHP 8.1.0+.

Installazione

L'SDK utilizza PSR-18 per HTTP e rileva automaticamente qualsiasi client PSR-18 installato. Guzzle è consigliato perché l'SDK lo configura per lo streaming senza alcuna configurazione aggiuntiva:

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

Requisiti

PHP 8.1.0 o superiore.

Utilizzo

Questa libreria utilizza parametri nominali per specificare gli argomenti opzionali. I parametri con un valore predefinito devono essere impostati per nome.

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

Per le opzioni di autenticazione, inclusa la Workload Identity Federation, consulta Autenticazione. Se la tua chiave API è una chiave personale o di account di servizio che non è limitata a un workspace, imposta l'ID del workspace nell'header di richiesta anthropic-workspace-id; Selezionare un workspace mostra l'opzione per singola richiesta per questo SDK.

Value object

Si consiglia di utilizzare il costruttore statico with Base64ImageSource::with(data: "U3RhaW5sZXNzIHJvY2tz", ...) e i parametri nominali per inizializzare i "value object" (oggetti valore).

Tuttavia, sono forniti anche i builder (new Base64ImageSource)->withData("U3RhaW5sZXNzIHJvY2tz").

Streaming

L'SDK fornisce il supporto per le risposte in "streaming" (streaming) utilizzando i 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;
}

Lo streaming richiede un client HTTP che restituisca il corpo della risposta in modo incrementale. Quando Guzzle è il client PSR-18 rilevato, l'SDK lo configura automaticamente per lo streaming. Con un client che esegue il buffering, il ciclo foreach restituisce tutti gli eventi in una volta sola al completamento della risposta anziché in modo incrementale; se osservi questo sintomo, installa Guzzle o fornisci un client PSR-18 compatibile con lo streaming tramite l'opzione di richiesta streamingTransporter:

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

Gestione degli errori

Quando la libreria non riesce a connettersi all'API, o se l'API restituisce un codice di stato di errore (ovvero una risposta 4xx o 5xx), viene lanciata una sottoclasse di 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();
}

I codici di errore sono i seguenti:

Tentativi ripetuti

Alcuni errori vengono ritentati automaticamente due volte per impostazione predefinita, con un breve backoff esponenziale.

Gli errori di connessione (ad esempio, a causa di un problema di connettività di rete), 408 Request Timeout, 409 Conflict, 429 Rate Limit, gli errori interni >=500 e i timeout vengono tutti ritentati per impostazione predefinita.

Puoi utilizzare l'opzione maxRetries per configurare o disabilitare questo comportamento:

use Anthropic\RequestOptions;
// ...
// Configura il valore predefinito per tutte le richieste:
$client = new Client(requestOptions: RequestOptions::with(maxRetries: 0));

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

Paginazione

I metodi di elenco nella Claude API sono paginati.

Questa libreria fornisce iteratori con paginazione automatica per ogni risposta di elenco, così non devi richiedere manualmente le pagine successive:

$client = new Client();

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

// recupera gli elementi dalla pagina corrente
foreach ($page->getItems() as $item) {
  echo $item->id, PHP_EOL;
}
// esegue ulteriori richieste di rete per recuperare gli elementi da tutte le pagine, dalla corrente in poi
// ...
foreach ($page->pagingEachItem() as $item) {
  echo $item->id, PHP_EOL;
// ...
}

Utilizzo avanzato

Tracciamento OpenTelemetry

Quando la tua applicazione registra un tracer provider OpenTelemetry, l'SDK emette uno span per ogni richiesta che invia. Per inviare gli span alla tua piattaforma di osservabilità, consulta Configurare OpenTelemetry con il Claude SDK.

Proprietà non documentate

Puoi inviare parametri non documentati a qualsiasi endpoint e leggere proprietà di risposta non documentate, come segue:

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

Parametri di richiesta non documentati

Se vuoi inviare esplicitamente un parametro aggiuntivo, puoi farlo con le opzioni extraQueryParams, extraBodyParams ed extraHeaders in RequestOptions::with() quando effettui una richiesta, come mostrato nell'esempio precedente.

Endpoint non documentati

Per effettuare richieste a endpoint non documentati mantenendo i vantaggi dell'autenticazione, dei tentativi ripetuti e delle altre funzionalità del client, puoi effettuare richieste utilizzando client->request, come segue:

$client = new Client();

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

Integrazioni con le piattaforme

L'SDK PHP supporta le seguenti piattaforme:

• Agent Platform: Anthropic\Vertex\Client. Usa ::fromEnvironment().
• Bedrock: Anthropic\Bedrock\MantleClient. Usa new MantleClient(awsRegion: ...).
• Bedrock (legacy): Anthropic\Bedrock\Client. Usa ::fromEnvironment() o ::withCredentials().
• Claude Platform on AWS: Anthropic\Aws\Client (richiede aws/aws-sdk-php come dipendenza opzionale). Usa new Anthropic\Aws\Client(workspaceId: ...) oppure imposta ANTHROPIC_AWS_WORKSPACE_ID. Disponibile in beta.
• Foundry: Anthropic\Foundry\Client. Usa ::withCredentials().

Usa MantleClient per i nuovi progetti; Anthropic\Bedrock\Client rimane disponibile per le applicazioni esistenti che utilizzano l'API InvokeModel di Bedrock.

L'SDK PHP supporta anche Claude Models on Google Cloud (Anthropic managed) tramite Anthropic\GoogleCloud\Client. Questo client è in beta. Anthropic\GoogleCloud\Client richiede google/auth come dipendenza opzionale. Usa new Anthropic\GoogleCloud\Client(workspaceId: ...) oppure imposta la variabile d'ambiente ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID. Consulta Risoluzione di progetto, location e workspace.

Versionamento semantico

Ogni versione major di questo SDK invia per impostazione predefinita una versione dell'API nell'header anthropic-version, e una nuova versione major accompagna ogni nuova versione dell'API. La prima versione major che invia 2026-10-21 è la 1.0.0; consulta Aggiornamento a 2026-10-21.

Questo pacchetto segue le convenzioni SemVer.

Questo pacchetto considera i miglioramenti alle definizioni di tipo PHPDoc (non di runtime) come modifiche non distruttive.

Risorse aggiuntive

• Repository GitHub
• Packagist
• Riferimento API
• Streaming dei messaggi