Anthropic Laravel

https://github.com/mozex/anthropic-laravel
Admin
Anthropic Laravel is a community-maintained Laravel integration package that provides a facade,...
Tokens:124,084
Snippets:875
Trust Score:8.6
License:MIT
Update:10 hours ago
Show doc for...
Tokens:
Raw
### Install and configure Anthropic Laravel package

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Run these commands to install the package and publish its configuration. The install command creates config/anthropic.php and adds ANTHROPIC_API_KEY to .env and .env.example with optional variables commented out.

```bash
composer require mozex/anthropic-laravel
php artisan anthropic:install
```

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

### Install development dependencies

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

Run this command after cloning your fork to install the necessary development dependencies.

```bash
composer install
```

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

### Run the install command

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

Publishes config/anthropic.php and adds ANTHROPIC_API_KEY= to .env with optional settings commented out.

```bash
php artisan anthropic:install
```

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

### Install via Composer

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

Install the package using Composer. Requires PHP 8.2+.

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

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

### Combine global and per-request betas

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

Global config and per-request betas stack and are de-duplicated. The example shows a stable beta in config and an experimental one per call; the request sends both values.

```php
// config/anthropic.php
'beta' => ['files-api-2025-04-14'], // always on

// Specific call adds another beta for this request only
Anthropic::messages()->create([
    'model' => 'claude-opus-5-5',
    'max_tokens' => 1024,
    'messages' => [...],
    'betas' => ['interleaved-thinking-2025-05-14'],
]);
// Sends: anthropic-beta: files-api-2025-04-14,interleaved-thinking-2025-05-14
```

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

### Use Anthropic::withOptions() for per-request options

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

Returns a client whose requests carry extra settings without altering the app-wide client. Use it to run one call in another workspace, add a beta for one feature, or tag requests for your gateway. The options include headers, query, betas, api_version, workspace_id, user_profile_id, and max_retries; methods that take only an ID, such as Anthropic::models()->retrieve(), get their betas this way.

```php
use Anthropic\Laravel\Facades\Anthropic;

$client = Anthropic::withOptions([
    'workspace_id' => $team->anthropic_workspace_id,
    'betas' => ['server-side-fallback-2026-07-01'],
    'headers' => ['X-Team' => (string) $team->id],
]);

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

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

### Configure Extended Thinking (Adaptive)

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Enables adaptive extended thinking on supported Claude models. Use the output_config effort parameter to guide reasoning depth.

```APIDOC
## Configure Extended Thinking (Adaptive)

### Description
Enables adaptive extended thinking on supported Claude models. Use the output_config effort parameter to guide reasoning depth.

### Parameters
#### Request Body
- `thinking` (object) - Required - `{'type' => 'adaptive'}`
- `output_config` (object) - Optional - `{'effort' => 'low'|'medium'|'high'|'xhigh'|'max'}`

### Notes
- Default on every Claude 5 model and opt-in on Opus 4.8, 4.7, 4.6 and Sonnet 4.6.
- `$model->capabilities?->effort` indicates which effort levels a model supports.
```

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

### Set up fake client with queued responses

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

Call Anthropic::fake() with an array of fake responses to replace the real client. The example queues a CreateResponse and then verifies the returned text. Once responses are queued, a call with none left throws.

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

Anthropic::fake([
    CreateResponse::fake([
        'content' => [['type' => 'text', 'text' => 'Hello! How can I help?']],
    ]),
]);

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

expect($response->content[0]->text)->toBe('Hello! How can I help?');
```

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

### Stream reply to browser via EventSource

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Return a streamed response from a GET route using toEventStream() for useEventStream. Pass glue: '' to avoid joining deltas with spaces. Check stop_reason in onMessage() for refusals.

```php
Route::get('/conversations/{conversation}/reply', fn (Conversation $conversation) => Anthropic::messages()
    ->createStreamed([...])
    ->onMessage(fn (CreateResponse $message) => $conversation->messages()->create(['role' => 'assistant', 'content' => $message->toArray()['content']]))
    ->toEventStream());
```

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

### Fake Anthropic client and assert sent request

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

Use Anthropic::fake() to mock the client, then assert the request sent. The example checks that the method is 'create' and the model is 'claude-sonnet-5-5'.

```php
use Anthropic\Laravel\Facades\Anthropic;
use Anthropic\Resources\Messages;
use Anthropic\Responses\Messages\CreateResponse;

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

// Run your code...
$this->post('/ask', ['question' => 'What is the capital of France?']);

// Then assert what was sent
Anthropic::assertSent(Messages::class, function (string $method, array $parameters): bool {
    return $method === 'create' && $parameters['model'] === 'claude-sonnet-5-5';
});
```

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

### Default config/anthropic.php structure

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Default configuration file published by the install command. All values are driven by environment variables, with request_timeout defaulting to 30 and max_retries to 0. The middleware and connections arrays are empty by default, and nightwatch is enabled by default.

```php
return [
    'api_key' => env('ANTHROPIC_API_KEY'),
    'auth_token' => env('ANTHROPIC_AUTH_TOKEN'),
    'workspace_id' => env('ANTHROPIC_WORKSPACE_ID'),
    'request_timeout' => env('ANTHROPIC_REQUEST_TIMEOUT', 30),
    'connect_timeout' => env('ANTHROPIC_CONNECT_TIMEOUT'),
    'max_retries' => env('ANTHROPIC_MAX_RETRIES', 0),
    'middleware' => [], // client middleware class names, e.g. Anthropic\Middleware\OpenTelemetryMiddleware
    'fallback_models' => array_values(array_filter(array_map(
        'trim',
        explode(',', (string) env('ANTHROPIC_FALLBACK_MODELS', ''))
    ))),
    'http' => [
        'middleware' => [],
        'laravel_client' => (bool) env('ANTHROPIC_HTTP_LARAVEL_CLIENT', false),
        'laravel_events' => (bool) env('ANTHROPIC_HTTP_LARAVEL_EVENTS', false),
        'telescope' => (bool) env('ANTHROPIC_HTTP_TELESCOPE', false),
        'nightwatch' => (bool) env('ANTHROPIC_HTTP_NIGHTWATCH', true),
    ],
    'context' => (bool) env('ANTHROPIC_CONTEXT', false),
    'headers' => [],
    'connections' => [], // 'support' => ['api_key' => env('ANTHROPIC_SUPPORT_API_KEY')], inheriting the rest
    'beta' => array_values(array_filter(array_map(
        'trim',
        explode(',', (string) env('ANTHROPIC_BETA', ''))
    ))),
    'api_version' => env('ANTHROPIC_API_VERSION'),
    'base_url' => env('ANTHROPIC_BASE_URL'),
];
```

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

### Resource-level assertions

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

Assert directly on a resource instance. The example shows assertSent with a callback on messages and assertNotSent on batches.

```php
Anthropic::messages()->assertSent(function (string $method, array $parameters): bool {
    return $method === 'create';
});

Anthropic::batches()->assertNotSent();
```

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

### Reference a file_id in a Messages call with beta header

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Pass the 'files-api-2025-04-14' beta on the Messages request when referencing a file_id, because the SDK does not auto-inject it there. The example sends a document block with a file source.

```php
Anthropic::messages()->create([
    'model' => 'claude-opus-5-5',
    'max_tokens' => 1024,
    'betas' => ['files-api-2025-04-14'],
    'messages' => [[
        'role' => 'user',
        'content' => [
            ['type' => 'text', 'text' => 'Summarise this.'],
            ['type' => 'document', 'source' => ['type' => 'file', 'file_id' => $file->id]],
        ],
    ]],
]);
```

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

### Configure client middleware in config/anthropic.php

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

Sets the 'middleware' key in the config file to run middleware around every client attempt with the PSR-7 request and next handler. Class names keep the config cacheable, and a connection can carry its own list. The OpenTelemetryMiddleware example requires the open-telemetry/api package.

```php
// config/anthropic.php
'middleware' => [
    \Anthropic\Middleware\OpenTelemetryMiddleware::class, // needs open-telemetry/api
],
```

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

### Set ANTHROPIC_BASE_URL for proxy or gateway

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

Use this environment variable to point the client at a proxy or AI gateway. The value is the URL without the API's '/v1'; the package adds '/v1' unless the URL already ends in it. The example sends requests to 'https://gateway.example.com/anthropic/v1/messages'. Note that Claude Code and official SDKs read the same variable, so a shell-exported value overrides '.env' for artisan commands and queue workers; use 'https://' to avoid sending the API key in clear text.

```env
ANTHROPIC_BASE_URL=https://gateway.example.com/anthropic
```

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

### Use a PDF from Laravel Storage with citations

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

Loads a PDF file from a Laravel storage disk, base64-encodes it, and sends it as a document content block with citations enabled. The 'media_type' is set to 'application/pdf' and the source type is 'base64'.

```php
use Illuminate\Support\Facades\Storage;

$pdf = Storage::disk('documents')->get('contract.pdf');

$response = Anthropic::messages()->create([
    'model' => 'claude-opus-5-5',
    'max_tokens' => 2048,
    'messages' => [
        [
            'role' => 'user',
            'content' => [
                [
                    'type' => 'document',
                    'source' => [
                        'type' => 'base64',
                        'media_type' => 'application/pdf',
                        'data' => base64_encode($pdf),
                    ],
                    'title' => 'Service Agreement',
                    'citations' => ['enabled' => true],
                ],
                ['type' => 'text', 'text' => 'What are the termination clauses?'],
            ],
        ],
    ],
]);
```

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

### Access MetaInformation from response, stream, or results

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Use `$response->meta()`, `$stream->meta()`, or `$results->meta()` to get a `MetaInformation` object. Provides request ID, rate limits, token limits, and retry-after. `priorityInputTokenLimit` and `priorityOutputTokenLimit` are null unless on Priority Tier; `fastInputTokenLimit` and `fastOutputTokenLimit` are null unless the request used fast mode. `retryAfter` is sent with 429s, so read it with `$e->getRetryAfter()`.

```php
$meta = $response->meta();
$meta->requestId;                                 // log this with every request
$meta->requestLimit->limit / ->remaining / ->reset;  // ISO 8601
$meta->tokenLimit->...;
$meta->inputTokenLimit->...;
$meta->outputTokenLimit->...;
$meta->priorityInputTokenLimit?->...;   // null unless on Priority Tier
$meta->priorityOutputTokenLimit?->...;
$meta->fastInputTokenLimit?->...;       // null unless the request used fast mode
$meta->fastOutputTokenLimit?->...;
$meta->organizationId;
$meta->workspaceId;
$meta->retryAfter;                      // seconds; sent with 429s, so read it with $e->getRetryAfter()
```

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

### Define a tool for Claude (get_weather)

Source: https://github.com/mozex/anthropic-laravel/blob/main/docs/usage/tool-use.md

Use the Anthropic Laravel facade to create a message with a custom tool definition. Claude decides when to call the tool based on the description and input schema. The example defines a 'get_weather' tool that requires a 'location' property.

```php
use Anthropic\Laravel\Facades\Anthropic;

$response = Anthropic::messages()->create([
    'model' => 'claude-sonnet-5-5',
    'max_tokens' => 1024,
    'tools' => [
        [
            'name' => 'get_weather',
            'description' => 'Get the current weather in a given location',
            'input_schema' => [
                'type' => 'object',
                'properties' => [
                    'location' => [
                        'type' => 'string',
                        'description' => 'The city and state, e.g. San Francisco, CA',
                    ],
                ],
                'required' => ['location'],
            ],
        ],
    ],
    'messages' => [
        ['role' => 'user', 'content' => 'What is the weather in San Francisco?'],
    ],
]);
```

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

### Make a raw API request with Anthropic::request()

Source: https://github.com/mozex/anthropic-laravel/blob/main/docs/usage/raw-requests.md

Use Anthropic::request() to call any API endpoint the package has no method for. Your key, config headers, retries, and withOptions() apply, and errors throw the same exceptions as other calls. GET and DELETE send parameters in the query string; POST and PUT send a JSON body; a 'betas' parameter becomes the 'anthropic-beta' header. The path works with or without the '/v1' prefix.

```php
use Anthropic\Laravel\Facades\Anthropic;
use Illuminate\Support\Facades\Cache;

// The first page; pass its next_page back as 'page' for the next one.
$skills = Cache::remember('anthropic.skills', now()->addHour(), function () {
    return Anthropic::request('GET', 'skills', ['limit' => 100])->data['data'];
});
```

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

### Download a file with Anthropic::files()->download() and store locally

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

Only files produced by the code execution tool or Skills can be downloaded; user-uploaded files cannot. Check `downloadable` first. `download()` returns raw bytes as a string. This example stores the bytes to a local disk.

```php
use Illuminate\Support\Facades\Storage;

$bytes = Anthropic::files()->download('file_011CPMxVD3fHLUhvTqtsQA5w');

Storage::disk('local')->put('outputs/chart.png', $bytes);
```

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

### Delete a file with Anthropic::files()->delete()

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

Deletes are permanent. In-flight Messages calls that already started may keep working briefly, but new requests using the same `file_id` get a 404. This example deletes the file and clears the stored ID.

```php
Anthropic::files()->delete($document->anthropic_file_id);

$document->update(['anthropic_file_id' => null]);
```

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

### Override fields in fake response

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

Use `Anthropic::fake()` with a response class's `fake()` method to override only specific fields; all other fields get default values. The example overrides `id` and `usage` for a `CreateResponse`.

```php
Anthropic::fake([
    CreateResponse::fake([
        'id' => 'msg_test_123',
        'usage' => ['input_tokens' => 100, 'output_tokens' => 50],
    ]),
]);
```

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

### Test streamed responses with CreateStreamedResponse::fake

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

Pass `CreateStreamedResponse::fake()` the response it should stream, and the fake sends the events the API would for it, including text deltas, thinking, and tool input. The example shows a Pest test that streams a reply and accumulates text deltas to assert the final text. Use `$stream->finalText()` to get the same text in one call.

```php
use Anthropic\Responses\Messages\CreateResponse;
use Anthropic\Responses\Messages\CreateStreamedResponse;
use Anthropic\Testing\Blocks;

it('streams the reply', function () {
    Anthropic::fake([
        CreateStreamedResponse::fake(CreateResponse::fake([
            'content' => [Blocks::text('Hello, world!')],
        ])),
    ]);

    $text = '';

    foreach (Anthropic::messages()->createStreamed([...]) as $event) {
        if ($event->type === 'content_block_delta' && $event->delta->type === 'text_delta') {
            $text .= $event->delta->text;
        }
    }

    expect($text)->toBe('Hello, world!');
});
```

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

### Run all tests

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

Execute the full test suite for the project.

```bash
composer test
```

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

### Publish and run the ledger migration

Source: https://github.com/mozex/anthropic-laravel/blob/main/docs/usage/usage-ledger.md

Run these artisan commands to publish and run the migration for the usage ledger. Do this before enabling the ledger.

```bash
php artisan vendor:publish --tag=anthropic-migrations
php artisan migrate
```

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

### Streaming to browser with POST and GET routes

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

Stores a user message via POST, then streams the reply from a GET route using `toEventStream()`. The `onMessage` callback saves the assistant reply. Note: each GET triggers a Claude call and billing, so only stream when the last message is the user's.

```php
use Anthropic\Laravel\Facades\Anthropic;
use Anthropic\Responses\Messages\CreateResponse;
use App\Models\Conversation;

Route::post('/conversations/{conversation}/messages', function (Conversation $conversation) {
    $conversation->messages()->create(['role' => 'user', 'content' => request('content')]);

    return response()->noContent();
});

Route::get('/conversations/{conversation}/reply', function (Conversation $conversation) {
    return Anthropic::messages()->createStreamed([
        'model' => 'claude-sonnet-5-5',
        'max_tokens' => 1024,
        'messages' => $conversation->messages()->orderBy('id')->get(['role', 'content'])->toArray(),
    ])
        // content has an array cast, so a reply's blocks go back as they came
        ->onMessage(fn (CreateResponse $message) => $conversation->messages()->create([
            'role' => 'assistant',
            'content' => $message->toArray()['content'],
        ]))
        ->toEventStream();
});
```

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

### Listen to broadcasted Claude events with useEcho

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

Subscribes to the broadcasted Claude events (claude.delta, claude.fallback, claude.done, claude.error) on a private channel. Event names start with a dot because they are not event classes. A sequence of 0 in claude.delta starts the reply over, as a retried job does.

```javascript
useEcho(`chat.${id}`, ['.claude.delta', '.claude.fallback', '.claude.done', '.claude.error'], (event) => {
    // event.text and event.sequence; a sequence of 0 starts the reply over, as a retried job does
});
```

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

### Enable beta per request via betas parameter

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

Pass a 'betas' array to any resource method. The SDK converts it to a one-request anthropic-beta header; the key is not sent in the JSON body or query string.

```php
use Anthropic\Laravel\Facades\Anthropic;

$response = Anthropic::messages()->create([
    'model' => 'claude-opus-5-5',
    'max_tokens' => 1024,
    'messages' => [
        ['role' => 'user', 'content' => 'Hello!'],
    ],
    'betas' => ['interleaved-thinking-2025-05-14'],
]);
```

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

### Meta on streams

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

Call meta() on the stream itself. The meta information comes from HTTP response headers, which arrive at the start of the stream.

```php
$stream = Anthropic::messages()->createStreamed([...]);

$meta = $stream->meta();
```

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

### Add api_version and base_url config keys

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

The package does not merge defaults into a published config file, so existing config/anthropic.php files lack the new api_version and base_url keys. Add these lines to enable the ANTHROPIC_API_VERSION and ANTHROPIC_BASE_URL environment variables.

```php
'api_version' => env('ANTHROPIC_API_VERSION'),
'base_url' => env('ANTHROPIC_BASE_URL'),
```

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

### List models with Anthropic::models()->list()

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Fetches the list of models from the Anthropic API. Each item is a full RetrieveResponse; fields like maxInputTokens, maxTokens, capabilities, firstId, and lastId can be null. Use the capabilities?->... optional chaining because capabilities can be null.

```php
$response = Anthropic::models()->list();

foreach ($response->data as $model) {
    $model->id;              // 'claude-sonnet-5-5'
    $model->displayName;
    $model->maxInputTokens;  // context window
    $model->maxTokens;       // max output
    $model->capabilities?->imageInput->supported;    // capabilities can be null
    $model->capabilities?->thinking->types->adaptive->supported;
    $model->capabilities?->effort->max->supported;
}
```

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

### Create a completion with Anthropic::completions()->create()

Source: https://github.com/mozex/anthropic-laravel/blob/main/docs/usage/completions.md

Deprecated API for text completions. Uses the claude-2.1 model and specific \n\nHuman: / \n\nAssistant: turn markers in the prompt. The response exposes completion, stop_reason, and model properties.

```php
use Anthropic\Laravel\Facades\Anthropic;

$response = Anthropic::completions()->create([
    'model' => 'claude-2.1',
    'prompt' => "\n\nHuman: Hello, Claude\n\nAssistant:",
    'max_tokens_to_sample' => 100,
    'temperature' => 0,
]);

$response->completion;  // ' Hello! Nice to meet you.'
$response->stop_reason; // 'stop_sequence'
$response->model;       // 'claude-2.1'
```

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

### Register event listener for ResponseReceived

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

Listens for `ResponseReceived` events and logs token usage and duration when usage is present. Register in a service provider's `boot()` method.

```php
use Anthropic\Laravel\Events\ResponseReceived;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Log;

Event::listen(function (ResponseReceived $event) {
    if ($event->usage !== null) {
        Log::info('Claude call', [
            'tokens' => $event->usage['input_tokens'] + $event->usage['output_tokens'],
            'ms' => $event->durationMs,
        ]);
    }
});
```

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

### Count tokens with Anthropic::messages()->countTokens()

Source: https://github.com/mozex/anthropic-laravel/blob/main/docs/reference/laravel-ai.md

Uses the same key laravel/ai sends prompts with. No additional setup needed for Anthropic::messages() to work.

```php
use Anthropic\Laravel\Facades\Anthropic;

// counted with the same key laravel/ai sends prompts with
$tokens = Anthropic::messages()->countTokens([
    'model' => 'claude-sonnet-5-5',
    'messages' => [['role' => 'user', 'content' => $prompt]],
])->inputTokens;
```

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

### Accessing Anthropic resources via the Facade

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Use the Anthropic facade as the sole entry point for application code. It provides access to messages, batches, models, files, and deprecated completions resources. Avoid instantiating Anthropic\Client directly; the container binding handles it.

```php
use Anthropic\Laravel\Facades\Anthropic;

Anthropic::messages();     // Messages resource
Anthropic::batches();      // Message Batches
Anthropic::models();       // Models
Anthropic::files();        // Files (upload, list, download, delete)
Anthropic::completions();  // Deprecated Text Completions: the API rejects it on current models
```

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

### Stream text deltas and get final message

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Iterate over text deltas from a streamed response and retrieve the final message. The loop ends at message_stop and skips ping events.

```php
foreach ($stream->text() as $delta) {   // text deltas only
    echo $delta;
}

$message = $stream->finalMessage();     // reads the rest; a CreateResponse as create() returns it
```

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

### delete

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

Permanently deletes a file. In-flight Messages calls may continue briefly, but new requests using the same file_id will get a 404.

```APIDOC
## delete

### Description
Permanently deletes a file. In-flight Messages calls may continue briefly, but new requests using the same file_id will get a 404.

### Method
delete

### Endpoint
Anthropic::files()->delete($fileId)

### Parameters
- **$fileId** (string) - Required - The Anthropic file ID.

### Request Example
```php
Anthropic::files()->delete($document->anthropic_file_id);
```

### Response
#### Success Response
No content returned.

#### Response Example
```php
$document->update(['anthropic_file_id' => null]);
```
```

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

### Add Advisor Tool (Beta)

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Adds an advisor tool that provides guidance. Its result blocks go back unchanged on later turns.

```APIDOC
## Add Advisor Tool (Beta)

### Description
Adds an advisor tool that provides guidance. Its result blocks go back unchanged on later turns.

### Parameters
#### Request Body
- `tools` (array) - Required - `['type' => 'advisor_20260301', 'name' => 'advisor', 'model' => 'claude-opus-5-5']`

### Notes
- Beta version: `advisor-tool-2026-03-01`.
- Result blocks are usually encrypted and must be passed back unchanged with the beta header.
```

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

### Throttling based on remaining limits

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

Check the remaining requests and throttle before hitting a 429. This example caches a throttle flag until the reset time.

```php
$response = Anthropic::messages()->create([...]);

$meta = $response->meta();

if ($meta->requestLimit->remaining < 10) {
    $reset = Carbon::parse($meta->requestLimit->reset);
    Cache::put('anthropic.throttle', true, $reset);
}
```

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

### Check types

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

Run static type analysis on the codebase.

```bash
composer test:types
```

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

### Lint the codebase

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

Execute the linting tool to ensure the code adheres to the project's coding style.

```bash
composer lint
```

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

### Upload, list, retrieve, download, and delete files

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Use these methods to manage files via the Anthropic Files API. Upload returns a FileResponse; download returns raw bytes and only works for files produced by Skills or code execution. The SDK auto-injects the beta header on all files() calls.

```php
$file = Anthropic::files()->upload(['file' => Storage::disk('local')->readStream('doc.pdf')]);
Anthropic::files()->list(['limit' => 100]);
Anthropic::files()->retrieveMetadata($fileId);
Anthropic::files()->download($fileId);  // raw bytes, only for skills/code-execution outputs
Anthropic::files()->delete($fileId);
```

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

### Rate limit properties

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

Access rate limit buckets for requests, tokens, input tokens, and output tokens. The example shows the available properties.

```php
$meta->requestLimit->limit;     // 3000
$meta->requestLimit->remaining; // 2999
$meta->requestLimit->reset;     // '2026-04-14T13:29:17Z'

$meta->tokenLimit->limit;     // 250000
$meta->tokenLimit->remaining; // 249984

$meta->inputTokenLimit->limit;
$meta->inputTokenLimit->remaining;

$meta->outputTokenLimit->limit;
$meta->outputTokenLimit->remaining;
```

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

### Run unit tests

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

Execute only the unit tests for the project.

```bash
composer test:unit
```

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

### Access the default Anthropic client via container or facade

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

The facade's root is the connection manager, and these calls all return the same singleton client. Type-hint ClientContract for the default client or AnthropicManager for every connection.

```php
app(\Anthropic\Contracts\ClientContract::class);
app('anthropic');
\Anthropic\Laravel\Facades\Anthropic::connection();
```

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

### Handle streaming citations_delta events

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

Iterates over a streaming response and checks for 'citations_delta' events. The citation data includes 'type' and 'cited_text' fields, accessible via $response->delta->citation.

```php
foreach ($stream as $response) {
    if ($response->delta->type === 'citations_delta') {
        $response->delta->citation['type'];      // 'char_location'
        $response->delta->citation['cited_text']; // 'The grass is green.'
    }
}
```

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

### Dispatching tool calls by toolset_name and name

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Handle tool_use blocks by checking toolset_name first. Member tools of computer/browser toolsets require echoing toolset_name in the result; custom tools have null toolset_name and use a registry. Never dispatch on name alone to avoid conflicts.

```php
foreach ($response->content as $block) {
    if ($block->type !== 'tool_use') {
        continue;
    }

    if ($block->toolset_name !== null) {
        $results[] = [
            'type' => 'tool_result',
            'tool_use_id' => $block->id,
            'toolset_name' => $block->toolset_name,
            'content' => app($toolsets[$block->toolset_name])->run($block->name, $block->input),
        ];

        continue;
    }

    $results[] = [
        'type' => 'tool_result',
        'tool_use_id' => $block->id,
        'content' => json_encode(app($toolRegistry[$block->name])->handle($block->input)),
    ];
}
```

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

### Basic streaming with createStreamed and text()

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

Streams Claude's response as it's generated. Iterate `$stream->text()` to get text deltas, and `finalMessage()` returns the whole response as `create()` would.

```php
use Anthropic\Laravel\Facades\Anthropic;

$stream = Anthropic::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 response, as create() would return it
```

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

### Replace the default HTTP client with a custom Guzzle client

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

Use extend() in a service provider's register() method to replace the default client with a custom PSR-18 implementation. The replacement is a new client, so carry over config values you rely on, like API version and betas. Use extend(), not singleton() or instance(), because the package's provider is deferred.

```php
use Anthropic;
use Anthropic\Contracts\ClientContract;
use GuzzleHttp\Client as Guzzle;

public function register(): void
{
    $this->app->extend(ClientContract::class, fn () => Anthropic::factory()
        ->withApiKey(config('anthropic.api_key'))
        ->withApiVersion((string) config('anthropic.api_version'))
        ->withHttpHeader('anthropic-beta', implode(',', config('anthropic.beta', [])))
        ->withHttpClient(new Guzzle(['timeout' => 120, 'connect_timeout' => 5]))
        ->make());
}
```

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

### Add MCP Connector (Beta)

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Connects to external MCP servers. Results come back as mcp_tool_use and mcp_tool_result blocks.

```APIDOC
## Add MCP Connector (Beta)

### Description
Connects to external MCP servers. Results come back as mcp_tool_use and mcp_tool_result blocks.

### Parameters
#### Request Body
- `mcp_servers` (array) - Required - `[['type' => 'url', 'url' => 'https://...', 'name' => 'crm', 'authorization_token' => $token]]`
- `tools` (array) - Required - `['type' => 'mcp_toolset', 'mcp_server_name' => 'crm']`

### Notes
- Beta version: `mcp-client-2025-11-20`.
- Under `mcp-client-2026-09-15`, a response can start with an `mcp_tool_listing` block, so don't assume `content[0]` is text.
- Result blocks: `mcp_tool_use` (`server_name`) and `mcp_tool_result` (`is_error`).
```

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

### Define a morphMany relation for billing sums

Source: https://github.com/mozex/anthropic-laravel/blob/main/docs/usage/usage-ledger.md

Adds an anthropicRequests relation to your model to sum usage. The billable columns are a morph, so $row->billable is the model. The example shows summing output_tokens for the current month.

```php
public function anthropicRequests(): MorphMany
{
    return $this->morphMany(\Anthropic\Laravel\Ledger\AnthropicRequest::class, 'billable');
}

$team->anthropicRequests()->where('created_at', '>=', now()->startOfMonth())->sum('output_tokens');
```

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

### Estimate cost before sending with countTokens()

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

Count tokens first to show users a cost estimate before billing. The example multiplies input tokens by a per-token rate and returns the estimate as JSON.

```php
$count = Anthropic::messages()->countTokens([
    'model' => $request->input('model'),
    'system' => $request->input('system'),
    'messages' => $request->input('messages'),
]);

$estimatedCost = $count->inputTokens * $inputRatePerToken;

return response()->json([
    'estimated_input_tokens' => $count->inputTokens,
    'estimated_cost' => $estimatedCost,
]);
```

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

### Compaction

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Describes how to use on-demand and threshold compaction with the Anthropic Laravel SDK. It explains the beta headers, the compaction block handling, and the expected behavior when sending the block back in subsequent requests.

```APIDOC
## Compaction

### Description
On-demand compaction (beta `compact-2026-09-04`, `'compaction' => ['type' => 'summarize']`) returns one signed `compaction` block with `stop_reason: 'compaction'`; any other stop reason means no summary, so keep the history. On every later request, with the same beta header, send the block exactly as `toArray()` returns it (`signature` included, no extra keys), first in `messages`, and drop the turns it summarized. Threshold compaction (`compact-2026-01-12`, `'context_management' => ['edits' => [['type' => 'compact_20260112']]]`) also expects its `compaction` block back unchanged.

### Parameters
#### Request Body
- `compaction` (object) - Required - Configuration for on-demand compaction: `['type' => 'summarize']`
- `context_management` (object) - Required - Configuration for threshold compaction: `['edits' => [['type' => 'compact_20260112']]]`

### Response
#### Success Response
- `compaction` block - Contains the signed compaction block with `stop_reason: 'compaction'`.

```

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

### Publish the Anthropic config file

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

Run this command to publish the config file manually. It leaves an existing config/anthropic.php alone unless you add --force, which overwrites your changes.

```bash
php artisan vendor:publish --tag=anthropic-config
```

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

### Send an image from Laravel Storage

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

If you're using Laravel's Storage facade, read the file and encode it inline. Uses `Storage::disk('s3')->get()` and `mimeType()` to fetch the file and its MIME type.

```php
use Illuminate\Support\Facades\Storage;

$file = Storage::disk('s3')->get('uploads/photo.jpg');
$mimeType = Storage::disk('s3')->mimeType('uploads/photo.jpg');

$response = Anthropic::messages()->create([
    'model' => 'claude-sonnet-5-5',
    'max_tokens' => 1024,
    'messages' => [
        [
            'role' => 'user',
            'content' => [
                ['type' => 'text', 'text' => 'Describe this photo.'],
                [
                    'type' => 'image',
                    'source' => [
                        'type' => 'base64',
                        'media_type' => $mimeType,
                        'data' => base64_encode($file),
                    ],
                ],
            ],
        ],
    ],
]);
```

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

### Configure Extended Thinking (Budget-based)

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Enables budget-based extended thinking on supported Claude models. Specify a token budget for reasoning.

```APIDOC
## Configure Extended Thinking (Budget-based)

### Description
Enables budget-based extended thinking on supported Claude models. Specify a token budget for reasoning.

### Parameters
#### Request Body
- `thinking` (object) - Required - `{'type' => 'enabled', 'budget_tokens' => 10000}`

### Notes
- Supported on Opus 4.5, Sonnet 4.5 and Haiku 4.5.
- Deprecated on Opus 4.6 and Sonnet 4.6; Claude 4.7 and later return a 400.
```

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

### Accessing meta information with meta()

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

Use the meta() method on any API response to access rate limit data, request IDs, and token limits. This example creates a message and retrieves the meta object.

```php
use Anthropic\Laravel\Facades\Anthropic;

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

$meta = $response->meta();
```

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

### Define tool with JSON Schema input_schema

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Define a tool for Claude using JSON Schema input_schema. Add 'strict' => true to guarantee schema-conformant output. Clear descriptions help Claude choose the right tool and arguments.

```php
'tools' => [[
    'name' => 'get_weather',
    'description' => 'Get the current weather in a given location',
    'input_schema' => [
        'type' => 'object',
        'properties' => [
            'location' => ['type' => 'string', 'description' => 'City and state, e.g. San Francisco, CA'],
        ],
        'required' => ['location'],
    ],
]]
```

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

### Pest fake with toHaveSent

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

Under Pest, keep the fake returned by Anthropic::fake() and pass it to expect(), since calling Anthropic::fake() again starts an empty one. toHaveSentTimes(), toHaveSentInOrder(), and toHaveSentNothing() work similarly.

```php
$fake = Anthropic::fake();

// run your code...

expect($fake)->toHaveSent(Messages::class)->toHaveSentOn('support', Messages::class);
```

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

### Access citation data from response content blocks

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

Shows how to read the text and citation details from the response's content blocks. The 'citations' array contains fields like 'type', 'cited_text', 'start_char_index', and 'end_char_index' for character locations.

```php
$response->content[1]->text;      // 'the grass is green'
$response->content[1]->citations[0]['type'];           // 'char_location'
$response->content[1]->citations[0]['cited_text'];     // 'The grass is green.'
$response->content[1]->citations[0]['start_char_index']; // 0
$response->content[1]->citations[0]['end_char_index'];   // 20
```

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

### Add Web Search Server Tool

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Adds Anthropic-hosted web search to the request. Results come back in the response.

```APIDOC
## Add Web Search Server Tool

### Description
Adds Anthropic-hosted web search to the request. Results come back in the response.

### Parameters
#### Request Body
- `tools` (array) - Required - `['type' => 'web_search_20250305', 'name' => 'web_search']`
- `max_uses` (integer) - Optional - Maximum number of uses.
- `allowed_domains` (array) - Optional - List of allowed domains.
- `blocked_domains` (array) - Optional - List of blocked domains.
- `user_location` (object) - Optional - User location for search.

### Notes
- Version `web_search_20260209` adds dynamic filtering and requires code execution enabled alongside.
```

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

### Create custom Anthropic client with factory

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Use this rare direct factory approach only when you need a custom HTTP client, headers, or stream handler. The API version, base URL, retries, refusal fallback, and Guzzle middleware have config keys, so this is not needed for those. Note that withStreamHandler is required for PSR-18 clients other than Guzzle/Symfony.

```php
$client = \Anthropic::factory() // the PHP client's class, not the facade
    ->withApiKey(config('anthropic.api_key'))
    ->withApiVersion('2026-10-21')
    ->withBaseUri('proxy.example.com/v1') // the full API root, /v1 included
    ->withHttpClient(new \GuzzleHttp\Client(['timeout' => 120]))
    ->withHttpHeader('X-Custom', 'value')
    ->withQueryParam('region', 'eu')
    ->withStreamHandler($handler) // required for PSR-18 clients other than Guzzle / Symfony
    ->make();
```

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

### Enable citations on a document content block

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

Creates a message with a document content block and enables citations via the 'citations' => ['enabled' => true] option. The response will contain multiple text blocks where cited claims include a 'citations' array.

```php
use Anthropic\Laravel\Facades\Anthropic;

$response = Anthropic::messages()->create([
    'model' => 'claude-opus-5-5',
    'max_tokens' => 1024,
    'messages' => [
        [
            'role' => 'user',
            'content' => [
                [
                    'type' => 'document',
                    'source' => [
                        'type' => 'text',
                        'media_type' => 'text/plain',
                        'data' => 'The grass is green. The sky is blue.',
                    ],
                    'title' => 'My Document',
                    'citations' => ['enabled' => true],
                ],
                ['type' => 'text', 'text' => 'What color is the grass and sky?'],
            ],
        ],
    ],
]);
```

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

### Answer by resource and method with respondTo

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

Use respondTo() to answer calls based on what was called rather than in order. Pass a resource class and method pair with a fake response. A responder answers every matching call; a stream is read only once, so pass a closure that builds a fresh one each time.

```php
use Anthropic\Resources\Models;
use Anthropic\Responses\Models\RetrieveResponse;

Anthropic::fake()->respondTo([Models::class, 'retrieve'], RetrieveResponse::fake());
```

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

### Handle refusal with stop_reason and stop_details

Source: https://github.com/mozex/anthropic-laravel/blob/main/resources/boost/skills/anthropic-laravel/SKILL.md

Use when safety classifiers intervene; the HTTP response is 200 and no exception is thrown. stop_details is null on normal completions, so guard before reading it. Treat category as the machine-readable signal; explanation text isn't stable between calls.

```php
if ($response->stop_reason === 'refusal') {
    Log::warning('Claude refused', [
        'user_id' => auth()->id(),
        'category' => $response->stop_details->category,    // 'cyber', 'bio', 'frontier_llm', 'reasoning_extraction', 'general_harms', or null
        'explanation' => $response->stop_details->explanation,
    ]);
    return back()->with('error', 'Your request could not be processed.');
}
```

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

### Run a Single Pest Test File

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

Executes a specific Pest test file using the vendor binary. Replace the path with your target test file.

```bash
./vendor/bin/pest tests/Facades/AnthropicTest.php
```
Tokens:
Raw