PHP SDK

Install and configure the Anthropic PHP SDK with value objects and builder patterns

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.

<?php

use Anthropic\Client;

$client = new Client(
  apiKey: getenv("ANTHROPIC_API_KEY") ?: "my-anthropic-api-key"
);

$message = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-4-7',
);

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).

<?php

use Anthropic\Client;

$client = new Client(
  apiKey: getenv("ANTHROPIC_API_KEY") ?: "my-anthropic-api-key"
);

$stream = $client->messages->createStream(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-4-7',
);

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\Client;

use Anthropic\Core\Exceptions\APIConnectionException;
use Anthropic\Core\Exceptions\APIStatusException;
use Anthropic\Core\Exceptions\RateLimitException;

$client = new Client();

try {
  $message = $client->messages->create(
    maxTokens: 1024,
    messages: [['role' => 'user', 'content' => 'Hello, Claude']],
    model: 'claude-opus-4-7',
  );
} 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:

<?php

use Anthropic\Client;
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-7',
  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:

<?php

use Anthropic\Client;

$client = new Client(
  apiKey: getenv("ANTHROPIC_API_KEY") ?: "my-anthropic-api-key"
);

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

use Anthropic\RequestOptions;

$client = new Client();

$message = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Claude']],
  model: 'claude-opus-4-7',
  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:

<?php
use Anthropic\Client;
$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