---
title: SDK PHP
url: https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/php
description: Instale e configure o SDK PHP da Anthropic com objetos de valor e padrões builder
---

A biblioteca PHP da Anthropic fornece acesso conveniente à Claude API a partir de qualquer aplicação PHP 8.1.0+.

<Info>
  O SDK PHP está atualmente em beta. As APIs podem mudar entre versões.
</Info>

<Info>
  Para documentação de recursos da API com exemplos de código, consulte a [referência da API](https://platform.claude.com/docs/pt-BR/api/overview). Esta página cobre recursos e configurações do SDK específicos para PHP.
</Info>

## Instalação

O SDK usa [PSR-18](https://www.php-fig.org/psr/psr-18/) para HTTP e descobre automaticamente qualquer cliente PSR-18 instalado. O [Guzzle](https://docs.guzzlephp.org/) é recomendado porque o SDK o configura para streaming sem nenhuma configuração adicional:

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

## Requisitos

PHP 8.1.0 ou superior.

## Uso

Esta biblioteca usa parâmetros nomeados para especificar argumentos opcionais. Parâmetros com um valor padrão devem ser definidos pelo 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;
```

Para opções de autenticação, incluindo Workload Identity Federation, consulte [Autenticação](https://platform.claude.com/docs/pt-BR/manage-claude/authentication). Se sua chave de API for uma [chave pessoal ou de conta de serviço](https://platform.claude.com/docs/pt-BR/manage-claude/authentication#key-types) com acesso a vários workspaces, defina o ID do workspace no cabeçalho de requisição `anthropic-workspace-id`; [Selecionar um workspace](https://platform.claude.com/docs/pt-BR/manage-claude/authentication#select-a-workspace) mostra a opção por requisição para este SDK.

## Objetos de valor

É recomendado usar o construtor estático `with` `Base64ImageSource::with(data: "U3RhaW5sZXNzIHJvY2tz", ...)` e parâmetros nomeados para inicializar "value objects" (objetos de valor).

No entanto, builders também são fornecidos `(new Base64ImageSource)->withData("U3RhaW5sZXNzIHJvY2tz")`.

## Streaming

O SDK oferece suporte a respostas em streaming usando "Server-Sent Events" (eventos enviados pelo servidor), ou 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;
}
```

O streaming requer um cliente HTTP que retorne o corpo da resposta de forma incremental. Quando o Guzzle é o cliente PSR-18 descoberto, o SDK o configura para streaming automaticamente. Com um cliente que faz buffering, o loop `foreach` produz todos os eventos de uma só vez quando a resposta é concluída, em vez de incrementalmente; se você observar esse sintoma, instale o Guzzle ou forneça um cliente PSR-18 com suporte a streaming por meio da opção de requisição `streamingTransporter`:

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

## Tratamento de erros

Quando a biblioteca não consegue se conectar à API, ou se a API retorna um código de status que não indica sucesso (ou seja, uma resposta 4xx ou 5xx), uma subclasse de `Anthropic\Core\Exceptions\APIException` é lançada:

```php
<?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();
}
```

Os códigos de erro são os seguintes:

| Causa           | Tipo de erro                   |
| --------------- | ------------------------------ |
| HTTP 400        | `BadRequestException`          |
| HTTP 401        | `AuthenticationException`      |
| HTTP 403        | `PermissionDeniedException`    |
| HTTP 404        | `NotFoundException`            |
| HTTP 409        | `ConflictException`            |
| HTTP 422        | `UnprocessableEntityException` |
| HTTP 429        | `RateLimitException`           |
| HTTP >= 500     | `InternalServerException`      |
| Outro erro HTTP | `APIStatusException`           |
| Timeout         | `APITimeoutException`          |
| Erro de rede    | `APIConnectionException`       |

## Novas tentativas

Certos erros são automaticamente repetidos duas vezes por padrão, com um curto backoff exponencial.

Erros de conexão (por exemplo, devido a um problema de conectividade de rede), 408 Request Timeout, 409 Conflict, 429 Rate Limit, erros internos >=500 e timeouts são todos repetidos por padrão.

Você pode usar a opção `maxRetries` para configurar ou desativar isso:

```php
use Anthropic\RequestOptions;
// ...
// Configure o padrão para todas as requisições:
$client = new Client(requestOptions: RequestOptions::with(maxRetries: 0));

// Ou configure por requisição:
$result = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-5-5',
  requestOptions: RequestOptions::with(maxRetries: 5),
);
```

## Paginação

Os métodos de listagem na Claude API são paginados.

Esta biblioteca fornece iteradores com paginação automática em cada resposta de listagem, para que você não precise solicitar páginas sucessivas manualmente:

```php
$client = new Client();

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

// busca itens da página atual
foreach ($page->getItems() as $item) {
  echo $item->id, PHP_EOL;
}
// faz requisições de rede adicionais para buscar itens de todas as páginas, incluindo a página atual e as seguintes
// ...
foreach ($page->pagingEachItem() as $item) {
  echo $item->id, PHP_EOL;
// ...
}
```

## Uso avançado

### Propriedades não documentadas

Você pode enviar parâmetros não documentados para qualquer endpoint e ler propriedades de resposta não documentadas, da seguinte forma:

<Note>
  Os parâmetros `extra*` com o mesmo nome substituem os parâmetros documentados.
</Note>

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

### Parâmetros de requisição não documentados

Se você quiser enviar explicitamente um parâmetro extra, pode fazê-lo com as opções `extraQueryParams`, `extraBodyParams` e `extraHeaders` em `RequestOptions::with()` ao fazer uma requisição, como visto no exemplo anterior.

### Endpoints não documentados

Para fazer requisições a endpoints não documentados mantendo o benefício de autenticação, novas tentativas e outros recursos do cliente, você pode fazer requisições usando `client->request`, da seguinte forma:

```php
$client = new Client();

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

## Integrações com plataformas

<Note>
  Para guias detalhados de configuração de plataformas com exemplos de código, consulte:

  * [Amazon Bedrock](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-amazon-bedrock)
  * [Amazon Bedrock (Opus 4.6 e anteriores)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-amazon-bedrock-legacy)
  * [Claude Platform na AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws)
  * [Google Cloud](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-vertex-ai)
  * [Microsoft Foundry](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry)
</Note>

O SDK PHP oferece suporte às seguintes plataformas:

* **Agent Platform:** `Anthropic\Vertex\Client`. Use `::fromEnvironment()`.
* **Bedrock:** `Anthropic\Bedrock\MantleClient`. Use `new MantleClient(awsRegion: ...)`.
* **Bedrock (legado):** `Anthropic\Bedrock\Client`. Use `::fromEnvironment()` ou `::withCredentials()`.
* **Claude Platform na AWS:** `Anthropic\Aws\Client` (requer `aws/aws-sdk-php` como dependência opcional). Use `new Anthropic\Aws\Client(workspaceId: ...)` ou defina `ANTHROPIC_AWS_WORKSPACE_ID`. Disponível em beta.
* **Foundry:** `Anthropic\Foundry\Client`. Use `::withCredentials()`.

Use `MantleClient` para novos projetos; `Anthropic\Bedrock\Client` permanece para aplicações existentes que usam a API `InvokeModel` do Bedrock.

## Versionamento semântico

Este pacote segue as convenções do [SemVer](https://semver.org/spec/v2.0.0.html). Como a biblioteca está em desenvolvimento inicial e tem uma versão principal `0`, as APIs podem mudar a qualquer momento.

Este pacote considera melhorias nas definições de tipo PHPDoc (não relacionadas ao tempo de execução) como alterações que não quebram compatibilidade.

## Recursos adicionais

* [Repositório no GitHub](https://github.com/anthropics/anthropic-sdk-php)
* [Packagist](https://packagist.org/packages/anthropic-ai/sdk)
* [Referência da API](https://platform.claude.com/docs/pt-BR/api/overview)
* [Streaming de mensagens](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming)