PHP SDK

The Anthropic PHP library provides convenient access to the Anthropic REST API from any PHP 8.1.0+ application.



Installation

The SDK uses PSR-18 for HTTP and discovers any installed PSR-18 client automatically. Guzzle is recommended because the SDK configures it for streaming with no additional setup:

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



Requirements

PHP 8.1.0 or higher.



Usage

This library uses named parameters to specify optional arguments. Parameters with a default value must be set by name.

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

For authentication options including Workload Identity Federation, see Authentication.



Value objects

It is recommended to use the static with constructor Base64ImageSource::with(data: "U3RhaW5sZXNzIHJvY2tz", ...) and named parameters to initialize value objects.

However, builders are also provided (new Base64ImageSource)->withData("U3RhaW5sZXNzIHJvY2tz").



Streaming

The SDK provides support for streaming responses using Server-Sent Events (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;
}

Streaming requires an HTTP client that returns the response body incrementally. When Guzzle is the discovered PSR-18 client, the SDK configures it for streaming automatically. With a buffering client, the foreach loop yields every event at once when the response completes instead of incrementally; if you observe that symptom, install Guzzle or supply a streaming-capable PSR-18 client through the streamingTransporter request option:

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



Error handling

When the library is unable to connect to the API, or if the API returns a non-success status code (that is, a 4xx or 5xx response), a subclass of Anthropic\Core\Exceptions\APIException is thrown:

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

Error codes are as follows:



Retries

Certain errors are automatically retried two times by default, with a short exponential backoff.

Connection errors (for example, because of a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts are all retried by default.

You can use the maxRetries option to configure or disable this:

use Anthropic\RequestOptions;
// ...
// Configure the default for all requests:
$client = new Client(requestOptions: RequestOptions::with(maxRetries: 0));

// Or, configure per-request:
$result = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-4-8',
  requestOptions: RequestOptions::with(maxRetries: 5),
);



Pagination

List methods in the Claude API are paginated.

This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:

$client = new Client();

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

// fetch items from the current page
foreach ($page->getItems() as $item) {
  echo $item->id, PHP_EOL;
}
// make additional network requests to fetch items from all pages, including and after the current page
foreach ($page->pagingEachItem() as $item) {
  echo $item->id, PHP_EOL;
}



Advanced usage



Undocumented properties

You can send undocumented parameters to any endpoint, and read undocumented response properties, as follows:

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



Undocumented request parameters

If you want to explicitly send an extra parameter, you can do so with the extraQueryParams, extraBodyParams, and extraHeaders options under RequestOptions::with() when making a request, as seen in the preceding example.



Undocumented endpoints

To make requests to undocumented endpoints while retaining the benefit of authentication, retries, and other client features, you can make requests using client->request, as follows:

$client = new Client();

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



Platform integrations

The PHP SDK supports the following platforms:

• Bedrock: Anthropic\Bedrock\MantleClient. Use new MantleClient(awsRegion: ...).
• Bedrock (legacy): Anthropic\Bedrock\Client. Use ::fromEnvironment() or ::withCredentials().
• Vertex AI: Anthropic\Vertex\Client. Use ::fromEnvironment().
• Foundry: Anthropic\Foundry\Client. Use ::withCredentials().
• Claude Platform on AWS: Anthropic\Aws\Client (requires aws/aws-sdk-php as a soft dependency). Use new Anthropic\Aws\Client(workspaceId: ...) or set ANTHROPIC_AWS_WORKSPACE_ID. Available in beta.

Use MantleClient for new projects; Anthropic\Bedrock\Client remains for existing applications using the Bedrock InvokeModel API.



Semantic versioning

This package follows SemVer conventions. As the library is in initial development and has a major version of 0, APIs might change at any time.

This package considers improvements to the (non-runtime) PHPDoc type definitions to be non-breaking changes.



Additional resources

• GitHub repository
• Packagist
• API reference
• Streaming Messages