--- title: SDK PHP url: https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/php description: Installa e configura l'SDK PHP di Anthropic con value object e pattern builder --- La libreria PHP di Anthropic fornisce un accesso comodo alla Claude API da qualsiasi applicazione PHP 8.1.0+. L'SDK PHP è attualmente in beta. Le API potrebbero cambiare tra una versione e l'altra. Per la documentazione delle funzionalità dell'API con esempi di codice, consulta il [riferimento API](https://platform.claude.com/docs/it/api/overview). Questa pagina tratta le funzionalità e la configurazione dell'SDK specifiche per PHP. ## Installazione L'SDK utilizza [PSR-18](https://www.php-fig.org/psr/psr-18/) per HTTP e rileva automaticamente qualsiasi client PSR-18 installato. [Guzzle](https://docs.guzzlephp.org/) è consigliato perché l'SDK lo configura per lo streaming senza alcuna configurazione aggiuntiva: ```bash 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. ```php $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](https://platform.claude.com/docs/it/manage-claude/authentication). Se la tua chiave API è una [chiave personale o di account di servizio](https://platform.claude.com/docs/it/manage-claude/authentication#key-types) con accesso a più workspace, imposta l'ID del workspace nell'header di richiesta `anthropic-workspace-id`; [Seleziona un workspace](https://platform.claude.com/docs/it/manage-claude/authentication#select-a-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. ```php $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 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`: ```php $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 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: | Causa | Tipo di errore | | ----------------- | ------------------------------ | | HTTP 400 | `BadRequestException` | | HTTP 401 | `AuthenticationException` | | HTTP 403 | `PermissionDeniedException` | | HTTP 404 | `NotFoundException` | | HTTP 409 | `ConflictException` | | HTTP 422 | `UnprocessableEntityException` | | HTTP 429 | `RateLimitException` | | HTTP >= 500 | `InternalServerException` | | Altro errore HTTP | `APIStatusException` | | Timeout | `APITimeoutException` | | Errore di rete | `APIConnectionException` | ## 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: ```php 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: ```php $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: I parametri `extra*` con lo stesso nome sovrascrivono i parametri documentati. ```php 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: ```php $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 Per guide dettagliate alla configurazione delle piattaforme con esempi di codice, consulta: * [Amazon Bedrock](https://platform.claude.com/docs/it/build-with-claude/claude-in-amazon-bedrock) * [Amazon Bedrock (Opus 4.6 e precedenti)](https://platform.claude.com/docs/it/build-with-claude/claude-on-amazon-bedrock-legacy) * [Claude Platform su AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws) * [Google Cloud](https://platform.claude.com/docs/it/build-with-claude/claude-on-vertex-ai) * [Microsoft Foundry](https://platform.claude.com/docs/it/build-with-claude/claude-in-microsoft-foundry) 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](https://semver.org/spec/v2.0.0.html). 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](https://github.com/anthropics/anthropic-sdk-php) * [Packagist](https://packagist.org/packages/anthropic-ai/sdk) * [Riferimento API](https://platform.claude.com/docs/it/api/overview) * [Streaming dei messaggi](https://platform.claude.com/docs/it/build-with-claude/streaming)