Changelog

All notable changes to anthropic-laravel will be documented in this file.

Server-side fallback for refused requests

On Claude Fable 5 and Opus 5 you can pass 'fallbacks' => 'default' with the server-side-fallback-2026-07-01 beta so the API retries a refused request on another model instead of returning the refusal. The response DTOs from anthropic-php 1.8.0 parse the whole flow: the fallback content block, per-attempt usage->iterations, and stop_details->recommended_model.

use Anthropic\Laravel\Facades\Anthropic;
use Illuminate\Support\Facades\Log;

$response = Anthropic::messages()->create([
    'model' => 'claude-fable-5',
    'max_tokens' => 1024,
    'fallbacks' => 'default',
    'betas' => ['server-side-fallback-2026-07-01'],
    'messages' => [['role' => 'user', 'content' => $prompt]],
]);

foreach ($response->usage->iterations ?? [] as $iteration) {
    if ($iteration->type === 'fallback_message') {
        Log::info('Served by fallback model', ['model' => $iteration->model]);
    }
}

Improved

Documentation

The Messages guide covers the expanded refusal categories (frontier_llm, reasoning_extraction, general_harms) and the new fallback section with a logging pattern, so refusal metrics don't misreport which model answered.
The Server Tools guide mentions the latest web_search_20260318 version and its response_inclusion parameter.

Boost skill

The refusal section of resources/boost/skills/anthropic-laravel/SKILL.md picks up the expanded category list and a pointer to the fallback flow, so AI assistants working in your app suggest current values.

Dependency

Bump mozex/anthropic-php to ^1.8.0. Everything in that release flows through the facade automatically: usage->outputTokensDetails (thinking token breakdown), usage->speed (fast mode), usage->iterations, compaction content blocks and context_management, and cache diagnostics. See the PHP 1.8.0 release notes for details and examples.

Full Changelog: 1.7.0...1.8.0

1.7.0 - 2026-04-18

What's Changed

Added

Files API

Anthropic::files() exposes the full Files resource: upload, list, retrieveMetadata, download, delete. Upload a document once and reference it by file_id in later Messages calls, or read outputs produced by the code execution tool and Skills.

use Anthropic\Laravel\Facades\Anthropic;
use Illuminate\Support\Facades\Storage;

$file = Anthropic::files()->upload([
    'file' => Storage::disk('local')->readStream('doc.pdf'),
]);

$response = Anthropic::messages()->create([
    'model' => 'claude-opus-4-6',
    '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]],
        ],
    ]],
]);

Anthropic currently flags this endpoint as beta. The SDK auto-injects the required anthropic-beta: files-api-2025-04-14 header on every Anthropic::files() call, so there's nothing to configure. When you reference a file_id inside a Messages call, pass 'betas' => ['files-api-2025-04-14'] on the Messages call as well; the Messages endpoint also needs the header when a file is referenced. If every Messages call in your app references uploaded files, put the beta globally via config('anthropic.beta') instead.

Testing

FileResponse::fake(), FileListResponse::fake(), and DeletedFileResponse::fake() now plug into Anthropic::fake([...]) with assertSent(Files::class, ...) assertions, same as every other resource.

Documentation

New Files guide covering upload, list, retrieve, download, delete, and Messages integration with Laravel-idiomatic patterns: Storage::readStream for uploads, queued jobs that stream downloads to S3, Eloquent anthropic_file_id columns, and the RateLimiter::for('anthropic-files', fn () => Limit::perMinute(90)) throttle for bulk uploads.

Boost skill

resources/boost/skills/anthropic-laravel/SKILL.md picks up a new Files section covering the five methods, the Messages-side beta gotcha, block-to-file-type pairing, and the Eloquent + queued-job patterns. Triggers expanded to include Anthropic::files(), FileResponse, and file upload/reference work.

Improved

Bump mozex/anthropic-php to ^1.7.0. See the PHP 1.7.0 release notes for the underlying implementation, including the auto-injection mechanism and the 40 Files-specific tests behind this release.

Full Changelog: 1.6.0...1.7.0

1.6.0 - 2026-04-18

What's Changed

Add Anthropic beta header support

Full Changelog: 1.5.0...1.6.0

1.5.0 - 2026-04-14

What's Changed

Added

Laravel Boost skill

Ship a Laravel Boost skill at resources/boost/skills/anthropic-laravel/SKILL.md so AI coding assistants pick up package conventions automatically when working in a Laravel project. Activates on any mention of the Anthropic facade, the underlying SDK classes, or Claude-related work.
Covers the full surface: messages, streaming, tool use, extended thinking, web search, code execution, citations, batches, token counting, models, testing with Anthropic::fake(), and error handling with the queue-retry pattern.
Calls out the five gotchas that actually cause bugs: inconsistent property casing across DTOs, the caller?->type === 'direct' filter required in tool dispatchers, pause_turn resume semantics, refusal responses arriving with HTTP 200, and mid-stream errors throwing after the response started.
Designed for progressive disclosure: keeps Laravel patterns and pitfalls in full, defers exhaustive reference material to Context7 (/mozex/anthropic-laravel, /mozex/anthropic-php) or direct fetches from the docs site, both of which serve markdown for AI agents.

Documentation site

Ship the full documentation at mozex.dev/docs/anthropic-laravel/v1 with dedicated pages for every feature: introduction, configuration, messages, streaming, tool use, thinking, server tools, citations, token counting, models, batches, completions, meta information, error handling, and testing.
Every page leads with Laravel-idiomatic examples: Facade calls, ShouldQueue jobs, Cache::remember for the model list, Storage::disk for vision and PDF citations, broadcasting from streamed responses, scheduled commands for batch polling, and bootstrap/app.php reportable() callbacks for silencing overload errors.
Each page links back to the matching page in the PHP SDK docs for deeper schema reference, so the Laravel docs stay focused on the 80% Laravel path without duplicating SDK material.

Improved

Bump mozex/anthropic-php to ^1.5.0. All API additions land transparently through the Anthropic facade: the caller object on tool blocks, container_upload blocks, stop_details on refusals, the typed model capabilities tree, inferenceGeo on usage, and Priority Tier rate-limit headers as typed properties on MetaInformation. See the PHP 1.5.0 release notes for the full feature list.