SDK PHP

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

$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 con accesso a più workspace, imposta l'ID del workspace nell'header di richiesta anthropic-workspace-id; Seleziona 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 nominati per inizializzare i "value objects" (oggetti valore).

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

Streaming

L'SDK fornisce il 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 che effettua il buffering, il ciclo foreach restituisce tutti gli eventi in una sola volta al completamento della risposta anziché in modo incrementale; se osservi questo sintomo, installa Guzzle oppure fornisci un client PSR-18 con supporto allo streaming tramite l'opzione di richiesta streamingTransporter:

$client = new Anthropic\Client(
  requestOptions: Anthropic\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 non di successo (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',
  );
} 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, 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 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;
}
// effettua richieste di rete aggiuntive per recuperare gli elementi da tutte le pagine, inclusa la pagina corrente e le 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 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 su 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.

Versionamento semantico

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

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

Risorse aggiuntive

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