Anthropic PHP

https://github.com/mozex/anthropic-php
Admin
PHP client for the Anthropic API: messages, streaming, tool use, thinking, web search, code...
Tokens:161,753
Snippets:1,115
Trust Score:8.6
License:MIT
Update:10 hours ago
Show doc for...
Tokens:
Raw
### Install dev dependencies with composer install

Source: https://github.com/mozex/anthropic-php/blob/main/CONTRIBUTING.md

Installs the development dependencies after cloning the fork.

```bash
composer install
```

--------------------------------

### Install with Composer

Source: https://github.com/mozex/anthropic-php/blob/main/README.md

Install the mozex/anthropic-php package via Composer. Requires PHP 8.2+.

```bash
composer require mozex/anthropic-php
```

--------------------------------

### Install Symfony HTTP Client via Composer

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Install the Symfony HTTP client, which also works without a custom stream handler.

```bash
composer require symfony/http-client
```

--------------------------------

### Install OpenTelemetry API via Composer

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Installs the open-telemetry/api package, which is only suggested by the package. Required for OpenTelemetryMiddleware.

```bash
composer require open-telemetry/api
```

--------------------------------

### Install Guzzle via Composer

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Install the Guzzle HTTP client, the most common choice for the Anthropic PHP SDK. Everything works out of the box, including streaming.

```bash
composer require guzzlehttp/guzzle
```

--------------------------------

### Install via Composer

Source: https://github.com/mozex/anthropic-php/blob/main/docs/introduction.md

Install the anthropic-php package using Composer. Requires PHP 8.2+.

```bash
composer require mozex/anthropic-php
```

--------------------------------

### Allow php-http/discovery Composer plugin

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Alternatively, allow the `php-http/discovery` Composer plugin to automatically install a PSR-18 client. This command sets the plugin permission in your project's Composer configuration.

```bash
composer config allow-plugins.php-http/discovery true
```

--------------------------------

### Use ClientFake to queue fake responses and assert requests

Source: https://github.com/mozex/anthropic-php/blob/main/README.md

Swap the real client with ClientFake in tests to queue fake responses and assert which requests were sent. No HTTP mocking libraries or test server needed. The example shows creating a fake response for a messages create call and asserting the model parameter.

```php
use Anthropic\Testing\ClientFake;
use Anthropic\Responses\Messages\CreateResponse;

$client = new ClientFake([
    CreateResponse::fake([
        'content' => [['type' => 'text', 'text' => 'Paris is the capital of France.']],
    ]),
]);

$response = $client->messages()->create([...]);

$client->assertSent(Messages::class, function (string $method, array $parameters): bool {
    return $parameters['model'] === 'claude-sonnet-5-5';
});
```

--------------------------------

### Composer Commands for anthropic-php

Source: https://github.com/mozex/anthropic-php/blob/main/CLAUDE.md

Lists the main Composer commands for installing dependencies, linting, testing, and checking type coverage. Use these in the project root.

```bash
composer install              # Install dependencies
composer lint                 # Fix code style (Pint)
composer test                 # Run ALL checks (lint, types, type-coverage, unit)
composer test:unit            # Run unit tests only (Pest)
composer test:types           # Run PHPStan (level max)
composer test:type-coverage   # Verify 100% type coverage
composer test:lint            # Check code style without fixing
```

--------------------------------

### Enable OpenTelemetry tracing with OpenTelemetryMiddleware

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Adds OpenTelemetry tracing to the client. Each attempt (including retries) gets a client span with GenAI semantic convention attributes. Prompts, answers, and keys are never recorded; failures to record never fail the request. The span is current during the request, and the registered propagator writes trace context into headers.

```php
use Anthropic\Middleware\OpenTelemetryMiddleware;

$client = Anthropic::factory()
    ->withApiKey('your-api-key')
    ->withMiddleware(new OpenTelemetryMiddleware)
    ->make();
```

--------------------------------

### Set global beta header on factory with withHttpHeader

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Configure a beta header globally on the Anthropic factory so it applies to every request, avoiding the need to pass `betas` per call. Global and per-request betas combine and are de-duplicated; for example, a global `interleaved-thinking-2025-05-14` plus a per-call `files-api-2025-04-14` sends both.

```php
$client = Anthropic::factory()
    ->withApiKey('your-api-key')
    ->withHttpHeader('anthropic-beta', 'interleaved-thinking-2025-05-14')
    ->make();
```

--------------------------------

### Set timeouts on the factory

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Set request and connect timeouts on the factory. These build a Guzzle client, so they require `guzzlehttp/guzzle` installed. A timeout that runs out throws a `TimeoutException`.

```php
$client = Anthropic::factory()
    ->withApiKey('your-api-key')
    ->withTimeout(300)        // seconds for a request; on a stream, Guzzle applies it to each read
    ->withConnectTimeout(5)   // seconds to connect
    ->make();
```

--------------------------------

### Add query parameter with withQueryParam

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Adds a query parameter to every request URL, useful for routing or analytics parameters required by proxy setups.

```php
->withQueryParam('my-param', 'bar')
```

--------------------------------

### Build content blocks with Blocks::thinking and Blocks::toolUse

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/testing.md

Use Blocks to construct content blocks for a fake's content, matching the API's shapes and IDs from the API docs' examples. Available methods include text(), toolUse(), thinking(), serverToolUse(), webSearchToolResult(), and webSearchResult(), each taking fields as arguments with defaults for the rest.

```php
use Anthropic\Testing\Blocks;

CreateResponse::fake([
    'content' => [
        Blocks::thinking('Let me check the weather.'),
        Blocks::toolUse('get_weather', ['location' => 'San Francisco, CA']),
    ],
    'stop_reason' => 'tool_use',
]);
```

--------------------------------

### Paginate backward with before_id and firstId

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/models.md

Paginates backward using before_id with firstId. This example fetches the previous page relative to $page2.

```php
$previousPage = $client->models()->list([
    'limit' => 5,
    'before_id' => $page2->firstId,
]);
```

--------------------------------

### Fake streamed response with SSE fixture file

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/testing.md

For streaming tests, pass a file resource containing SSE event data to CreateStreamedResponse::fake. The example creates a streamed client and asserts the first event type is 'message_start'.

```php
use Anthropic\Testing\ClientFake;
use Anthropic\Responses\Messages\CreateStreamedResponse;

$client = new ClientFake([
    CreateStreamedResponse::fake(fopen('tests/fixtures/stream.txt', 'r')),
]);

$stream = $client->messages()->createStreamed([
    'model' => 'claude-sonnet-5-5',
    'max_tokens' => 1024,
    'messages' => [
        ['role' => 'user', 'content' => 'Hello!'],
    ],
]);

expect($stream->getIterator()->current())
    ->type->toBe('message_start');
```

--------------------------------

### Pest expectations with expect()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/testing.md

Under Pest, a fake works with expect() using toHaveSent, toHaveSentTimes, toHaveSentInOrder, and not->toHaveSent. toHaveSentOn() and toHaveSentNothing() follow assertSentOn() and assertNothingSent(). They're registered the first time a fake is made, and only when Pest is installed.

```php
expect($client)
    ->toHaveSent(Messages::class)
    ->toHaveSentTimes(Messages::class, 2)
    ->toHaveSentInOrder([Models::class, Messages::class])
    ->not->toHaveSent(Batches::class);
```

--------------------------------

### Configure updates thinking display with beta

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/thinking.md

Use the 'updates' display option to get short progress notes before tool calls. Requires the beta header 'thinking-display-updates-2026-08-18' and is available on Fable 5.1, Mythos 5.1, Fable 5, Opus 5.5 and Sonnet 5.5. Reasoning blocks stay empty; only progress blocks right before a tool call carry text.

```php
$response = $client->messages()->create([
    'model' => 'claude-opus-5-5',
    'max_tokens' => 16000,
    'betas' => ['thinking-display-updates-2026-08-18'],
    'thinking' => [
        'type' => 'adaptive',
        'display' => 'updates',
    ],
    'tools' => $tools,
    'messages' => $messages,
]);

$response->content[1]->thinking; // 'Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call.'
```

--------------------------------

### Paginate forward with limit and after_id

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/models.md

Uses cursor-based pagination. limit controls page size (defaults to 20, max 1000) and after_id fetches the next page. The example fetches the first page with limit 5, then the next page if more exist.

```php
// First page
$page1 = $client->models()->list(['limit' => 5]);

// Next page (if more exist)
if ($page1->hasMore) {
    $page2 = $client->models()->list([
        'limit' => 5,
        'after_id' => $page1->lastId,
    ]);
}
```

--------------------------------

### Fakes per connection with onConnection and assertSentOn

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/testing.md

When using a framework that hands out one client per connection (e.g., Laravel's Anthropic::connection()), each connection gets its own view of a fake. onConnection('support') shares the queue and recorded requests, recording its own under that name. assertSentOn() checks which connection a call used; assertNotSentOn() verifies absence. Calls through the fake itself carry no connection name; a subclass can set the protected $connection property to assign one.

```php
$fake = new ClientFake([CreateResponse::fake()]);

$fake->onConnection('support')->messages()->create([...]);

$fake->assertSentOn('support', Messages::class);
$fake->assertSentOn('support', Messages::class, 1); // exactly once
$fake->assertNotSentOn('billing', Messages::class);
```

--------------------------------

### Per-request options with withOptions()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Use withOptions() to create a client with extra request settings without modifying the original client. Options include workspace_id, betas, and headers. The returned client carries these settings on subsequent requests, while the original remains unchanged.

```php
$tenant = $client->withOptions([
    'workspace_id' => 'wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ',
    'betas' => ['server-side-fallback-2026-07-01'],
    'headers' => ['X-Request-Source' => 'billing-report'],
]);

$tenant->models()->retrieve('claude-sonnet-5-5'); // carries all three
$client->models()->retrieve('claude-sonnet-5-5'); // carries none of them
```

--------------------------------

### Access signature on content block start

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/streaming.md

When thinking is enabled, the content block start event includes a signature field that is initially empty and gets filled by the signature delta.

```php
$response->content_block_start->signature; // ''
```

--------------------------------

### Get meta information from streamed responses

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/meta-information.md

For streamed responses, call `meta()` on the stream object to get the MetaInformation object. The meta information comes from the HTTP response headers set at the start of the stream.

```APIDOC
## Get meta information from streamed responses

### Description
For streamed responses, call `meta()` on the stream object to get the MetaInformation object. The meta information comes from the HTTP response headers set at the start of the stream.

### Method
`meta()`

### Endpoint
`$stream->meta()`

### Parameters
None

### Response
- **MetaInformation** (object) - The meta information object containing response headers.

### Response Example
```php
$stream = $client->messages()->createStreamed([
    'model' => 'claude-sonnet-5-5',
    'max_tokens' => 1024,
    'messages' => [
        ['role' => 'user', 'content' => 'Hello, world'],
    ],
]);

$stream->meta(); // same MetaInformation object
```
```

--------------------------------

### Configure Anthropic client with factory options

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Chains all factory options and calls make() to create the client. Each with* method returns the factory for chaining.

```php
$client = Anthropic::factory()
    ->withApiKey('your-api-key')
    ->withWorkspaceId('wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ')
    ->withApiVersion('2026-10-21')
    ->withBaseUri('anthropic.example.com/v1')
    ->withHttpClient($httpClient)
    ->withHttpHeader('X-Custom-Header', 'value')
    ->withQueryParam('my-param', 'bar')
    ->withStreamHandler($streamHandler)
    ->make();
```

--------------------------------

### Get meta information from streamed response with $stream->meta()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/meta-information.md

For streamed responses, call `meta()` on the stream object, not on individual events. The meta information comes from HTTP response headers set at the start of the stream.

```php
$stream = $client->messages()->createStreamed([
    'model' => 'claude-sonnet-5-5',
    'max_tokens' => 1024,
    'messages' => [
        ['role' => 'user', 'content' => 'Hello, world'],
    ],
]);

$stream->meta(); // same MetaInformation object
```

--------------------------------

### make()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Creates the Anthropic client instance with the configured options. Must be called at the end of the factory chain.

```APIDOC
## make()

### Description
Creates the Anthropic client instance with the configured options. Must be called at the end of the factory chain.

### Method
Factory method

### Endpoint
`make()`

### Parameters
None

### Response
Returns an Anthropic client instance.

### Request Example
```php
->make()
```
```

--------------------------------

### Override response fields with CreateResponse::fake

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/testing.md

Use ClientFake with CreateResponse::fake to override only the fields you need for a test; unspecified fields get default values. The example overrides stop_reason and usage output_tokens, then asserts the response values.

```php
use Anthropic\Responses\Messages\CreateResponse;

$client = new ClientFake([
    CreateResponse::fake([
        'stop_reason' => 'max_tokens',
        'usage' => ['output_tokens' => 1024],
    ]),
]);

$response = $client->messages()->create([
    'model' => 'claude-sonnet-5-5',
    'max_tokens' => 1024,
    'messages' => [
        ['role' => 'user', 'content' => 'Write a long story.'],
    ],
]);

expect($response->stop_reason)->toBe('max_tokens')
    ->and($response->usage->outputTokens)->toBe(1024);
```

--------------------------------

### Configure client with factory

Source: https://github.com/mozex/anthropic-php/blob/main/docs/introduction.md

Use the factory for more control over the client, including API key, version, base URI, custom HTTP client, headers, query params, and stream handler.

```php
$client = Anthropic::factory()
    ->withApiKey('your-api-key')
    ->withApiVersion('2026-10-21')
    ->withBaseUri('anthropic.example.com/v1')
    ->withHttpClient(new \GuzzleHttp\Client(['timeout' => 120]))
    ->withHttpHeader('X-Custom-Header', 'value')
    ->withQueryParam('my-param', 'bar')
    ->withStreamHandler(fn ($request) => $httpClient->send($request, [
        'stream' => true,
    ]))
    ->make();
```

--------------------------------

### Get meta information from batch results with $results->meta()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/meta-information.md

Batch result responses also support `meta()`, which returns rate limit headers for the request. The example shows retrieving results by batch ID and iterating over them before calling `meta()`.

```php
$results = $client->batches()->results('msgbatch_04Rka1yCsMLGPnR7kfPdgR8x');

// Process results...
foreach ($results as $individual) {
    // ...
}

$results->meta(); // rate limit headers for this request
```

--------------------------------

### Create client and send message

Source: https://github.com/mozex/anthropic-php/blob/main/docs/introduction.md

Create a client with your API key and send a message. The create method returns a CreateResponse object with typed properties.

```php
$client = Anthropic::client('your-api-key');

$response = $client->messages()->create([
    'model' => 'claude-sonnet-5-5',
    'max_tokens' => 1024,
    'messages' => [
        ['role' => 'user', 'content' => 'Hello!'],
    ],
]);

echo $response->content[0]->text; // Hello! How can I assist you today?
```

--------------------------------

### Collect text blocks from response content

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/messages.md

Collects all text blocks to get the answer's text, since Claude 5 models think by default and the reply may start with a thinking block. Do not assume the answer is content[0].

```php
$text = '';

foreach ($response->content as $block) {
    if ($block->type === 'text') {
        $text .= $block->text;
    }
}
```

--------------------------------

### Build client with withConfig()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Use withConfig() to apply settings from a framework config array, following the same rules as the Laravel package. Keys include api_key, workspace_id, betas, max_retries, and headers. Invalid keys or values throw before any settings are applied.

```php
$client = Anthropic::factory()
    ->withConfig([
        'api_key' => getenv('ANTHROPIC_API_KEY'),
        'workspace_id' => 'wrkspc_011CZkZaBF1tNoB5wlCeusgy',
        'betas' => ['compact-2026-09-04'],
        'max_retries' => 2,
        'headers' => ['X-Request-Source' => 'billing-report'],
    ])
    ->make();
```

--------------------------------

### Access stream metadata with createStreamed

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/streaming.md

Retrieve rate limit headers and request metadata from a streamed message response using the stream object's meta() method. The example creates a streamed message with model 'claude-sonnet-5-5' and then calls meta() to get a MetaInformation object.

```php
$stream = $client->messages()->createStreamed([
    'model' => 'claude-sonnet-5-5',
    'max_tokens' => 1024,
    'messages' => [
        ['role' => 'user', 'content' => 'Hello!'],
    ],
]);

$stream->meta(); // MetaInformation object with rate limits
```

--------------------------------

### withConfig()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Builds a client from a configuration array, applying the same rules as the Laravel package. It accepts keys like api_key, workspace_id, betas, max_retries, and headers, and validates the input before applying.

```APIDOC
## withConfig()

### Description
Builds a client from a configuration array, applying the same rules as the Laravel package. It accepts keys like api_key, workspace_id, betas, max_retries, and headers, and validates the input before applying.

### Method
withConfig()

### Parameters
#### Request Body
- **api_key** (string) - Optional - API key for authentication.
- **auth_token** (string) - Optional - Used only when there's no api_key.
- **workspace_id** (string) - Optional - Workspace identifier.
- **api_version** (string) - Optional - API version.
- **base_url** (string) - Optional - Base URL without /v1.
- **base_uri** (string) - Optional - Full API root.
- **betas** (array|string) - Optional - List of betas or comma-separated string.
- **timeout** (number) - Optional - Timeout in seconds.
- **connect_timeout** (number) - Optional - Connection timeout in seconds.
- **max_retries** (integer) - Optional - Number of retries.
- **middleware** (callable|array) - Optional - Middleware callable(s).
- **http_client** (object) - Optional - HTTP client instance.
- **headers** (array) - Optional - Additional headers.

### Response
#### Success Response
Returns a configured Anthropic client instance.

### Request Example
```php
$client = Anthropic::factory()
    ->withConfig([
        'api_key' => getenv('ANTHROPIC_API_KEY'),
        'workspace_id' => 'wrkspc_011CZkZaBF1tNoB5wlCeusgy',
        'betas' => ['compact-2026-09-04'],
        'max_retries' => 2,
        'headers' => ['X-Request-Source' => 'billing-report'],
    ])
    ->make();
```
```

--------------------------------

### withHttpClient()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Provides a custom PSR-18 HTTP client. If not set, the factory uses `php-http/discovery` to find a compatible client automatically.

```APIDOC
## withHttpClient()

### Description
Provides a custom PSR-18 HTTP client. If not set, the factory uses `php-http/discovery` to find a compatible client automatically.

### Method
Factory method

### Endpoint
`withHttpClient(Psr\Http\Client\ClientInterface $httpClient)`

### Parameters
- **$httpClient** (Psr\Http\Client\ClientInterface) - Required - The HTTP client to use.

### Response
Returns the factory instance for chaining.

### Request Example
```php
->withHttpClient(new \GuzzleHttp\Client(['timeout' => 120]))
```
```

--------------------------------

### Custom configuration with factory

Source: https://github.com/mozex/anthropic-php/blob/main/README.md

Use the factory to set a custom base URI, HTTP client, and headers. The withApiKey method is required; other methods are optional.

```php
$client = Anthropic::factory()
    ->withApiKey('your-api-key')
    ->withBaseUri('anthropic.example.com/v1')
    ->withHttpClient(new \GuzzleHttp\Client(['timeout' => 120]))
    ->withHttpHeader('X-Custom-Header', 'value')
    ->make();
```

--------------------------------

### Multiple sequential requests with ClientFake

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/testing.md

Fake responses are consumed in order: the first request gets the first response, the second gets the second, and so on. If more requests are made than fake responses, the next call throws an exception naming the call, e.g., 'No fake responses left. Messages::create() was the next call: ...'

```php
$client = new ClientFake([
    CreateResponse::fake(['content' => [['type' => 'text', 'text' => 'First']]]),
    CreateResponse::fake(['content' => [['type' => 'text', 'text' => 'Second']]]),
]);

$first = $client->messages()->create([...]); // Returns "First"
$second = $client->messages()->create([...]); // Returns "Second"
```

--------------------------------

### Anthropic::factory()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Creates a new Anthropic client factory instance. Use the with* methods to configure the client and call make() to create the client.

```APIDOC
## Anthropic::factory()

### Description
Creates a new Anthropic client factory instance. Use the with* methods to configure the client and call make() to create the client.

### Method
Factory method

### Endpoint
`Anthropic::factory()`

### Parameters
None

### Response
Returns a factory instance that can be chained with configuration methods.

### Request Example
```php
$client = Anthropic::factory()
    ->withApiKey('your-api-key')
    ->withWorkspaceId('wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ')
    ->withApiVersion('2026-10-21')
    ->withBaseUri('anthropic.example.com/v1')
    ->withHttpClient($httpClient)
    ->withHttpHeader('X-Custom-Header', 'value')
    ->withQueryParam('my-param', 'bar')
    ->withStreamHandler($streamHandler)
    ->make();
```
```

--------------------------------

### Iterate over all models with iterate()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/models.md

Walks every page using iterate(). It takes the same parameters as list(), follows after_id from page to page (or before_id when starting with one), and yields one model at a time. Returns a generator, so nothing is requested until the loop starts; breaking early saves remaining requests. iterator_to_array() collects all models into one array.

```php
foreach ($client->models()->iterate(['limit' => 100]) as $model) {
    $model->id; // 'claude-opus-5-5', 'claude-sonnet-5-5', ...
}
```

--------------------------------

### withOptions()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Returns a new client with per-request options applied, leaving the original client unchanged. It merges options when called on a client that already has options, and throws an InvalidArgumentException for unknown options.

```APIDOC
## withOptions()

### Description
Returns a new client with per-request options applied, leaving the original client unchanged. It merges options when called on a client that already has options, and throws an InvalidArgumentException for unknown options.

### Method
withOptions()

### Parameters
#### Request Body
- **headers** (array) - Optional - Extra headers as name => value pairs.
- **query** (array) - Optional - Extra query parameters.
- **betas** (array) - Optional - Betas added to the anthropic-beta header.
- **api_version** (string) - Optional - The anthropic-version header.
- **workspace_id** (string) - Optional - The anthropic-workspace-id header.
- **user_profile_id** (string) - Optional - The anthropic-user-profile-id header.
- **max_retries** (integer) - Optional - Number of retries.

### Response
#### Success Response
Returns a new client with the specified options applied.

### Request Example
```php
$tenant = $client->withOptions([
    'workspace_id' => 'wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ',
    'betas' => ['server-side-fallback-2026-07-01'],
    'headers' => ['X-Request-Source' => 'billing-report'],
]);

$tenant->models()->retrieve('claude-sonnet-5-5'); // carries all three
$client->models()->retrieve('claude-sonnet-5-5'); // carries none of them
```
```

--------------------------------

### Request ID

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/meta-information.md

Every request gets a unique identifier accessible via $meta->requestId.

```php
$meta->requestId; // 'req_012nTzj6kLoP8vZ1SGANvcgR'
```

--------------------------------

### Set HTTP client with withHttpClient

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Provide a PSR-18 HTTP client. If not set, the factory uses php-http/discovery to find a compatible client automatically.

```php
->withHttpClient(new \GuzzleHttp\Client(['timeout' => 120]))
```

--------------------------------

### Get batch results

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/batches.md

Retrieves the results of a completed batch, with methods to access successful results.

```APIDOC
## [RESULTS] /batches/{id}/results

### Description
Retrieves the results of a completed batch, with methods to access successful results.

### Method
RESULTS

### Endpoint
`$client->batches()->results($batchId)`

### Parameters
#### Path Parameters
- **batchId** (string) - Required - The ID of the batch to retrieve results for.

### Request Example
```php
foreach ($client->batches()->results($batch->id)->succeeded() as $individual) {
    // process individual result
}
```

### Response
#### Success Response
- **succeeded()** (iterable) - An iterable of individual results, each with `customId` and `result` properties.

#### Response Example
```php
$individual->customId; // 'custom-id'
$individual->result->message; // message object
```
```

--------------------------------

### Create client from environment with Anthropic::fromEnvironment()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Reads ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN when no key is set, ANTHROPIC_BASE_URL, and ANTHROPIC_CUSTOM_HEADERS (one 'Name: value' header per line). Throws InvalidArgumentException when neither credential is set.

```php
$client = Anthropic::fromEnvironment();
```

--------------------------------

### Cancel a batch

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/batches.md

Cancels a batch that is still processing. In-progress requests will finish, but no new requests will start.

```APIDOC
## [CANCEL] /batches/{id}

### Description
Cancels a batch that is still processing. In-progress requests will finish, but no new requests will start.

### Method
CANCEL

### Endpoint
`$client->batches()->cancel($batchId)`

### Parameters
#### Path Parameters
- **batchId** (string) - Required - The ID of the batch to cancel.

### Request Example
```php
$response = $client->batches()->cancel('msgbatch_04Rka1yCsMLGPnR7kfPdgR8x');
```

### Response
#### Success Response
- **processingStatus** (string) - The new status of the batch, e.g., 'canceling'.

#### Response Example
```php
$response->processingStatus; // 'canceling'
```
```

--------------------------------

### Cancel a batch

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/batches.md

Cancels a batch that is still processing. In-progress requests will finish, but no new requests will start.

```php
$response = $client->batches()->cancel('msgbatch_04Rka1yCsMLGPnR7kfPdgR8x');

$response->processingStatus; // 'canceling'
```

--------------------------------

### Configure logging with withLogger()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Sets up a PSR-3 logger on the Anthropic client. Each attempt logs an info line with method, URL, and attempt number; responses log status, request ID, and duration; retries log a warning with delay and reason. Bodies and headers are never logged.

```php
$client = Anthropic::factory()
    ->withApiKey('your-api-key')
    ->withLogger($logger)
    ->make();
```

--------------------------------

### Streaming response

Source: https://github.com/mozex/anthropic-php/blob/main/README.md

Create a streamed message and print text deltas as they arrive. Use finalMessage() to get the full CreateResponse object after streaming.

```php
$stream = $client->messages()->createStreamed([
    'model' => 'claude-sonnet-5-5',
    'max_tokens' => 1024,
    'messages' => [
        ['role' => 'user', 'content' => 'Tell me a short story.'],
    ],
]);

foreach ($stream->text() as $delta) {
    echo $delta;
}

$message = $stream->finalMessage(); // the whole CreateResponse, as if it hadn't streamed
```

--------------------------------

### createStreamed()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/streaming.md

Starts a streaming request to the Messages API. Returns a StreamResponse object that can be iterated over to receive incremental updates as they are generated.

```APIDOC
## createStreamed()

### Description
Starts a streaming request to the Messages API. Returns a StreamResponse object that can be iterated over to receive incremental updates as they are generated.

### Method
createStreamed

### Parameters
#### Request Body
- **model** (string) - Required - The model to use for the request.
- **max_tokens** (integer) - Required - The maximum number of tokens to generate.
- **messages** (array) - Required - An array of message objects, each with a role and content.

### Response
#### Success Response
- **StreamResponse** - An iterable object that yields CreateStreamedResponse objects.

### Request Example
```php
$stream = $client->messages()->createStreamed([
    'model' => 'claude-sonnet-5-5',
    'max_tokens' => 1024,
    'messages' => [
        ['role' => 'user', 'content' => 'Hello!'],
    ],
]);
```

### Response Example
```php
foreach ($stream as $response) {
    echo $response->toArray()['type']; // event type
}
```
```

--------------------------------

### Retrieve model with beta options

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/models.md

Use `withOptions()` to pass beta headers to `retrieve()`, which only takes an ID. Access beta-only compaction capability.

```php
$model = $client->withOptions(['betas' => ['compact-2026-09-04']])->models()->retrieve('claude-opus-5-5');

$model->capabilities?->compaction?->summarize->supported;
```

--------------------------------

### Get meta information from batch results

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/meta-information.md

Batch result responses also support `meta()` to retrieve rate limit headers for the request.

```APIDOC
## Get meta information from batch results

### Description
Batch result responses also support `meta()` to retrieve rate limit headers for the request.

### Method
`meta()`

### Endpoint
`$results->meta()`

### Parameters
None

### Response
- **MetaInformation** (object) - The meta information object containing rate limit headers.

### Response Example
```php
$results = $client->batches()->results('msgbatch_04Rka1yCsMLGPnR7kfPdgR8x');

// Process results...
foreach ($results as $individual) {
    // ...
}

$results->meta(); // rate limit headers for this request
```
```

--------------------------------

### withOptions() - Set per-request options

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/models.md

Sets per-request options, such as beta headers, for the client. This method is used to pass beta headers to retrieve() which only takes an ID.

```APIDOC
## withOptions()

### Description
Sets per-request options, such as beta headers, for the client. This method is used to pass beta headers to retrieve() which only takes an ID.

### Method
withOptions

### Parameters
#### Request Body
- **betas** (array) - Optional - List of beta header values.

### Request Example
```php
$model = $client->withOptions(['betas' => ['compact-2026-09-04']])->models()->retrieve('claude-opus-5-5');
```

### Response
#### Success Response (200)
- **model** (object) - The model object with capabilities.

#### Response Example
```json
{
  "capabilities": {
    "compaction": {
      "supported": true,
      "summarize": { "supported": true }
    }
  }
}
```
```

--------------------------------

### Retrieve file metadata

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/files.md

GET on a single file. Returns the same response shape as upload. Shows filename, mimeType, sizeBytes, and downloadable.

```php
$file = $client->files()->retrieveMetadata('file_011CNha8iCJcU1wXNR6q4V8w');

$file->filename;     // 'document.pdf'
$file->mimeType;     // 'application/pdf'
$file->sizeBytes;    // 1024000
$file->downloadable; // false
```

--------------------------------

### Create client and send message

Source: https://github.com/mozex/anthropic-php/blob/main/README.md

Create an Anthropic client with your API key, send a message, and read the response text. The response content is accessed via $response->content[0]->text.

```php
$client = Anthropic::client('your-api-key');

$response = $client->messages()->create([
    'model' => 'claude-sonnet-5-5',
    'max_tokens' => 1024,
    'messages' => [
        ['role' => 'user', 'content' => 'Hello!'],
    ],
]);

echo $response->content[0]->text; // Hello! How can I assist you today?
```

--------------------------------

### Trim conversation to fit and create message

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/token-counting.md

Calls trimToFit() to drop oldest turns until the request fits, then passes the returned parameters to create(). It only cuts before a user turn that answers no tool call, preserving tool_result pairs and keeping the conversation starting with the user. A request that already fits is returned unchanged after one count; otherwise it counts a few more times, halving its way to a cut that fits. Throws Anthropic\Exceptions\InvalidArgumentException when even the last turn it can start from is over the limit.

```php
$parameters = $client->messages()->trimToFit($parameters, 150000);

$response = $client->messages()->create($parameters);
```

--------------------------------

### Create client with Anthropic::client()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Creates a client using auto-discovered defaults: official Anthropic API endpoint, a PSR-18 HTTP client via php-http/discovery, and standard headers. Suitable for most projects.

```php
$client = Anthropic::client('your-api-key');
```

--------------------------------

### withApiKey()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Sets the API key used for authentication. The client sends this as a `x-api-key` header on every request. Leading and trailing whitespace is trimmed automatically.

```APIDOC
## withApiKey()

### Description
Sets the API key used for authentication. The client sends this as a `x-api-key` header on every request. Leading and trailing whitespace is trimmed automatically.

### Method
Factory method

### Endpoint
`withApiKey(string $apiKey)`

### Parameters
- **$apiKey** (string) - Required - The API key to use.

### Response
Returns the factory instance for chaining.

### Request Example
```php
->withApiKey('your-api-key')
```
```

--------------------------------

### List models with beta headers

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/models.md

Pass beta headers to `list()` to access beta-only fields like `allowedFallbackModels` and `compaction`. Each is null without its header.

```php
$models = $client->models()->list(['betas' => ['server-side-fallback-2026-07-01', 'compact-2026-09-04']])->data;

foreach ($models as $model) {
    $model->allowedFallbackModels;                            // the models a refusal on this one may fall back to
    $model->capabilities?->compaction?->supported;            // compaction support
    $model->capabilities?->compaction?->summarize->supported; // on-demand compaction (`'compaction' => ['type' => 'summarize']`)
}
```

--------------------------------

### Stream callbacks

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/streaming.md

Attach callbacks to a stream to process events as they are read. Callbacks run before your loop gets the event, so they work even when you only call finalMessage().

```APIDOC
## Stream callbacks

### Description
Attach callbacks to a stream to process events as they are read. Callbacks run before your loop gets the event, so they work even when you only call finalMessage().

### Methods
- `onText(callable $callback)` - Registers a callback that receives each text delta.
- `onContentBlock(callable $callback)` - Registers a callback that receives each content block once it stops (e.g., a tool call with its input decoded).
- `onEvent(callable $callback)` - Registers a callback that receives each event object.
- `onThinking(callable $callback)` - Registers a callback that receives each thinking delta.
- `onMessage(callable $callback)` - Registers a callback that receives the whole message at `message_stop`.
- `currentMessage()` - Returns the message so far inside a text callback.

### Usage
```php
use Anthropic\Responses\Messages\CreateResponseContent;

$message = $stream
    ->onText(fn (string $delta) => print($delta))
    ->onContentBlock(fn (CreateResponseContent $block) => $block->type === 'tool_use' ? $tools->queue($block) : null)
    ->finalMessage();
```

### Notes
- A callback only sees what's read after you add it.
- To get the message so far inside a text callback, call `currentMessage()`.
- A callback cannot read the stream it's called from (that throws a `LogicException`).
```

--------------------------------

### Run unit tests with composer test:unit

Source: https://github.com/mozex/anthropic-php/blob/main/CONTRIBUTING.md

Runs the unit test suite.

```bash
composer test:unit
```

--------------------------------

### Build stream from explicit events

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/testing.md

For exact control, pass an array of events to CreateStreamedResponse::fake(), each with its 'type' field. The example shows message_start, content_block_delta, and message_stop events.

```php
CreateStreamedResponse::fake([
    ['type' => 'message_start', 'message' => [...]],
    ['type' => 'content_block_delta', 'index' => 0, 'delta' => ['type' => 'text_delta', 'text' => 'Hello']],
    ['type' => 'message_stop'],
]);
```

--------------------------------

### Lint code with composer lint

Source: https://github.com/mozex/anthropic-php/blob/main/CONTRIBUTING.md

Runs the coding style linter as required by the contribution guidelines.

```bash
composer lint
```

--------------------------------

### Get thinking token usage from message delta

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/streaming.md

When thinking is enabled, the final message_delta usage includes the thinking token count via outputTokensDetails->thinkingTokens.

```php
$response->usage->outputTokensDetails?->thinkingTokens; // 150
```

--------------------------------

### assertSentWithOptions with withOptions()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/testing.md

withOptions() on the fake returns a fake that shares its queue and recorded requests. Each request records the options, and assertSentWithOptions() checks them. The expected options can be a subset; a request carrying more options still matches, and header names match whatever their spelling.

```php
use Anthropic\Resources\Messages;

$client = new ClientFake([CreateResponse::fake()]);

// the code under test
$client->withOptions(['workspace_id' => 'wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ'])->messages()->create([...]);

$client->assertSent(Messages::class, 1);
$client->assertSentWithOptions(Messages::class, ['workspace_id' => 'wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ']);
```

--------------------------------

### Iterate through all batches with iterate()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/batches.md

Uses iterate() to walk through every page of batches, following lastId, and yields one batch at a time. Nothing is requested until the loop starts.

```php
foreach ($client->batches()->iterate(['limit' => 100]) as $batch) {
    if ($batch->processingStatus === 'in_progress') {
        // ...
    }
}
```

--------------------------------

### Create multi-turn conversation with messages()->create()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/messages.md

Send the full message history in each request because the API is stateless. Messages must alternate between user and assistant roles, starting with a user message.

```php
$response = $client->messages()->create([
    'model' => 'claude-sonnet-5-5',
    'max_tokens' => 1024,
    'messages' => [
        ['role' => 'user', 'content' => 'What is PHP?'],
        ['role' => 'assistant', 'content' => 'PHP is a server-side scripting language...'],
        ['role' => 'user', 'content' => 'What version should I use?'],
    ],
]);
```

--------------------------------

### Streaming citations with citations_delta events

Source: https://github.com/mozex/anthropic-php/blob/main/docs/usage/citations.md

When streaming, citations arrive as `citations_delta` events on the delta object. The example shows how to create a streamed message with a document and a text prompt, then iterate over the stream to access citation details.

```php
$stream = $client->messages()->createStreamed([
    'model' => 'claude-opus-5-5',
    'max_tokens' => 1024,
    'messages' => [
        [
            'role' => 'user',
            'content' => [
                [
                    'type' => 'document',
                    'source' => [
                        'type' => 'text',
                        'media_type' => 'text/plain',
                        'data' => 'PHP 8.4 was released on November 21, 2024.',
                    ],
                    'title' => 'Release Notes',
                    'citations' => ['enabled' => true],
                ],
                [
                    'type' => 'text',
                    'text' => 'When was PHP 8.4 released?',
                ],
            ],
        ],
    ],
]);

foreach ($stream as $response) {
    if ($response->delta->type === 'citations_delta') {
        $response->delta->citation['type'];      // 'char_location'
        $response->delta->citation['cited_text']; // 'PHP 8.4 was released on November 21, 2024.'
    }
}
```

--------------------------------

### Read client settings with settings()

Source: https://github.com/mozex/anthropic-php/blob/main/docs/reference/configuration.md

Use `settings()` on a client to retrieve the configuration sent with every request. The returned object exposes properties like `baseUri`, `apiVersion`, `betas`, `workspaceId`, `maxRetries`, `timeout`, and `connectTimeout`. It never contains the API key or token; timeouts are only known for the Guzzle client built by the factory, otherwise they are `null`. `toArray()` returns all settings as an array.

```php
$settings = $client->settings();

$settings->baseUri;        // 'https://api.anthropic.com/v1/'
$settings->apiVersion;     // '2023-06-01'
$settings->betas;          // ['compact-2026-09-04']
$settings->workspaceId;    // null
$settings->maxRetries;     // 2
$settings->timeout;        // 120.0
$settings->connectTimeout; // null
```

--------------------------------

### ClientContract and TransporterContract withOptions() method signatures

Source: https://github.com/mozex/anthropic-php/blob/main/UPGRADING.md

Required for implementers of ClientContract and TransporterContract. Returns a client or transporter whose requests carry extra headers, query parameters, betas, API version, workspace, or user profile. ClientFake implements it, sharing its queue with the fake it returns.

```php
// ClientContract
public function withOptions(array $options): ClientContract;

// TransporterContract
public function withOptions(array $options): self;
```

--------------------------------

### Run all tests with composer test

Source: https://github.com/mozex/anthropic-php/blob/main/CONTRIBUTING.md

Runs all tests for the project.

```bash
composer test
```
Tokens:
Raw