SDK PHP

La libreria PHP di Anthropic fornisce un accesso comodo all'API REST di Anthropic 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 denominati per specificare 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',
);

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



Value object

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

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



Streaming

L'SDK fornisce supporto per le risposte in streaming utilizzando i "Server-Sent Events" (eventi inviati dal server), o 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;
}

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 con buffering, il ciclo foreach restituisce tutti gli eventi in una volta sola quando la risposta viene completata invece che in modo incrementale; se osservi questo sintomo, installa Guzzle o fornisci un client PSR-18 con capacità di streaming tramite l'opzione di richiesta streamingTransporter:

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



Gestione degli errori

Quando la libreria non è in grado di connettersi all'API, o se l'API restituisce un codice di stato di non successo (cioè 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',
  );
} 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 automaticamente ritentati due volte per impostazione predefinita, con un breve "exponential backoff" (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, 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',
  requestOptions: RequestOptions::with(maxRetries: 5),
);



Paginazione

I metodi di elenco nell'API di Claude sono paginati.

Questa libreria fornisce iteratori con paginazione automatica per ogni risposta di elenco, quindi 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;
}
// effettua richieste di rete aggiuntive per recuperare gli elementi da tutte le pagine, inclusa la pagina corrente e quelle successive
foreach ($page->pagingEachItem() as $item) {
  echo $item->id, PHP_EOL;
}



Utilizzo avanzato



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',
  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 e extraHeaders sotto 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 su AWS: Anthropic\Aws\Client (richiede aws/aws-sdk-php come dipendenza soft). Usa new Anthropic\Aws\Client(workspaceId: ...) o imposta ANTHROPIC_AWS_WORKSPACE_ID. Disponibile in beta.
• Foundry: Anthropic\Foundry\Client. Usa ::withCredentials().

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



Versionamento semantico

Questo pacchetto segue le convenzioni SemVer. Poiché la libreria è in fase di sviluppo iniziale e ha una versione principale 0, le API potrebbero cambiare in qualsiasi momento.

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



Risorse aggiuntive

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