1# Claude API — PHP
2 
3> **Note:** The PHP SDK is the official Anthropic SDK for PHP. A beta tool runner is available via `$client->beta->messages->toolRunner()`. Structured output helpers are supported via `StructuredOutputModel` classes. Agent SDK is not available. Bedrock, Vertex AI, and Foundry clients are supported.
4 
5## Installation
6 
7```bash
8composer require "anthropic-ai/sdk"
9```
10 
11## Client Initialization
12 
13```php
14use Anthropic\Client;
15 
16// Using API key from environment variable
17$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
18```
19 
20### Amazon Bedrock
21 
22```php
23use Anthropic\Bedrock\MantleClient;
24 
25// Messages-API Bedrock endpoint. Reads AWS credentials from env.
26$client = new MantleClient(awsRegion: 'us-east-1');
27```
28 
29Model IDs on Bedrock take an `anthropic.` prefix — e.g. `model: 'anthropic.claude-opus-4-8'`.
30 
31### Google Vertex AI
32 
33```php
34use Anthropic\Vertex;
35 
36// Constructor is private. Parameter is `location`, not `region`.
37$client = Vertex\Client::fromEnvironment(
38    location: 'us-east5',
39    projectId: 'my-project-id',
40);
41```
42 
43### Anthropic Foundry
44 
45```php
46use Anthropic\Foundry;
47 
48// Constructor is private. baseUrl or resource is required.
49$client = Foundry\Client::withCredentials(
50    apiKey: getenv('ANTHROPIC_FOUNDRY_API_KEY'),
51    baseUrl: 'https://<resource>.services.ai.azure.com/anthropic/v1',
52);
53```
54 
55---
56 
57## Basic Message Request
58 
59```php
60$message = $client->messages->create(
61    model: 'claude-opus-4-8',
62    maxTokens: 16000,
63    messages: [
64        ['role' => 'user', 'content' => 'What is the capital of France?'],
65    ],
66);
67 
68// content is an array of polymorphic blocks (TextBlock, ToolUseBlock,
69// ThinkingBlock). Accessing ->text on content[0] without checking the block
70// type will throw if the first block is not a TextBlock (e.g., when extended
71// thinking is enabled and a ThinkingBlock comes first). Always guard:
72foreach ($message->content as $block) {
73    if ($block->type === 'text') {
74        echo $block->text;
75    }
76}
77```
78 
79If you only want the first text block:
80 
81```php
82foreach ($message->content as $block) {
83    if ($block->type === 'text') {
84        echo $block->text;
85        break;
86    }
87}
88```
89 
90---
91 
92## Extended Thinking
93 
94**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think.
95 
96```php
97use Anthropic\Messages\ThinkingBlock;
98 
99$message = $client->messages->create(
100    model: 'claude-opus-4-8',
101    maxTokens: 16000,
102    thinking: ['type' => 'adaptive', 'display' => 'summarized'], // display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Opus 4.8 / 4.7
103    messages: [
104        ['role' => 'user', 'content' => 'Solve: 27 * 453'],
105    ],
106);
107 
108// ThinkingBlock(s) precede TextBlock in content
109foreach ($message->content as $block) {
110    if ($block instanceof ThinkingBlock) {
111        echo "Thinking:\n{$block->thinking}\n\n";
112        // $block->signature is an opaque string — preserve verbatim if
113        // passing thinking blocks back in multi-turn conversations
114    } elseif ($block->type === 'text') {
115        echo "Answer: {$block->text}\n";
116    }
117}
118```
119 
120> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking (above). `['type' => 'enabled', 'budgetTokens' => N]` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
121> **Older models:** Use `thinking: ['type' => 'enabled', 'budgetTokens' => N]` (budget must be < `maxTokens`, min 1024).
122 
123`$block->type === 'thinking'` also works for the check; `instanceof` narrows for PHPStan.
124 
125---
126 
127## Prompt Caching
128 
129`system:` takes an array of text blocks; set `cacheControl` on the last block. Array-shape syntax (camelCase keys) is idiomatic. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
130 
131```php
132$message = $client->messages->create(
133    model: 'claude-opus-4-8',
134    maxTokens: 16000,
135    system: [
136        ['type' => 'text', 'text' => $longSystemPrompt, 'cacheControl' => ['type' => 'ephemeral']],
137    ],
138    messages: [['role' => 'user', 'content' => 'Summarize the key points']],
139);
140```
141 
142For 1-hour TTL: `'cacheControl' => ['type' => 'ephemeral', 'ttl' => '1h']`. There's also a top-level `cacheControl:` on `messages->create(...)` that auto-places on the last cacheable block.
143 
144Verify hits via `$message->usage->cacheCreationInputTokens` / `$message->usage->cacheReadInputTokens`.
145 
146---
147 
148## Stop Details
149 
150When `stopReason` is `'refusal'`, the response includes structured `stopDetails`:
151 
152```php
153if ($message->stopReason === 'refusal' && $message->stopDetails !== null) {
154    echo "Category: " . $message->stopDetails->category . "\n";     // e.g. "cyber", "bio", "reasoning_extraction", "frontier_llm", or null — see docs for the full set
155    echo "Explanation: " . $message->stopDetails->explanation . "\n";
156}
157```
158 
159**Refusal fallbacks (Claude Fable 5) — opt in by default.** Fallbacks are opt-in: without them a refused request simply stops. New `claude-fable-5` code should include the server-side `fallbacks` parameter (beta header `server-side-fallback-2026-06-01`, fallback model `claude-opus-4-8`, on the beta messages call) by default. The exact PHP binding (and the client-side middleware for providers without server-side support) is not documented here — WebFetch the PHP SDK repo's `examples/` from `shared/live-sources.md`; full semantics in `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason.
160 
161---
162 
163## Error Type
164 
165`APIStatusException` exposes a `->type` property for programmatic error classification:
166 
167```php
168try {
169    $client->messages->create(...);
170} catch (\Anthropic\Core\Exceptions\APIStatusException $e) {
171    echo $e->type?->value;  // "rate_limit_error", "overloaded_error", etc.
172}
173```
174