SDK PHP

La libreria PHP di Anthropic fornisce un accesso pratico alla REST API 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 nominati 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-4-8',
);

echo $message->content[0]->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 nominati per inizializzare i value object.

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

Streaming

L'SDK fornisce supporto per le risposte in streaming utilizzando "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-4-8',
);

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 utilizza il buffering, il ciclo foreach produce tutti gli eventi in una volta sola quando la risposta è completa invece che 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 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 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-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();
}

I codici di errore sono i seguenti:

Tentativi di ripetizione

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-4-8',
  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 è necessario 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 quella 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-4-8',
  requestOptions: RequestOptions::with(
    extraQueryParams: ['my_query_parameter' => 'value'],
    extraBodyParams: ['my_body_parameter' => 'value'],
    extraHeaders: ['my-header' => 'value'],
  ),
);

Parametri di richiesta non documentati

Se desideri inviare esplicitamente un parametro aggiuntivo, puoi farlo con le opzioni extraQueryParams, extraBodyParams e 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 di ripetizione e di 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:

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

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 principale 0, le API potrebbero cambiare in qualsiasi momento.

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

Risorse aggiuntive

• Repository GitHub
• Packagist
• Riferimento API
• Messaggi in streaming