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;
24 
25// Constructor is private — use the static factory. Reads AWS credentials from env.
26$client = Bedrock\Client::fromEnvironment(region: 'us-east-1');
27```
28 
29### Google Vertex AI
30 
31```php
32use Anthropic\Vertex;
33 
34// Constructor is private. Parameter is `location`, not `region`.
35$client = Vertex\Client::fromEnvironment(
36    location: 'us-east5',
37    projectId: 'my-project-id',
38);
39```
40 
41### Anthropic Foundry
42 
43```php
44use Anthropic\Foundry;
45 
46// Constructor is private. baseUrl or resource is required.
47$client = Foundry\Client::withCredentials(
48    authToken: getenv('ANTHROPIC_FOUNDRY_AUTH_TOKEN'),
49    baseUrl: 'https://<resource>.services.ai.azure.com/anthropic',
50);
51```
52 
53---
54 
55## Basic Message Request
56 
57```php
58$message = $client->messages->create(
59    model: 'claude-opus-4-7',
60    maxTokens: 16000,
61    messages: [
62        ['role' => 'user', 'content' => 'What is the capital of France?'],
63    ],
64);
65 
66// content is an array of polymorphic blocks (TextBlock, ToolUseBlock,
67// ThinkingBlock). Accessing ->text on content[0] without checking the block
68// type will throw if the first block is not a TextBlock (e.g., when extended
69// thinking is enabled and a ThinkingBlock comes first). Always guard:
70foreach ($message->content as $block) {
71    if ($block->type === 'text') {
72        echo $block->text;
73    }
74}
75```
76 
77If you only want the first text block:
78 
79```php
80foreach ($message->content as $block) {
81    if ($block->type === 'text') {
82        echo $block->text;
83        break;
84    }
85}
86```
87 
88---
89 
90## Streaming
91 
92> **Requires SDK v0.5.0+.** v0.4.0 and earlier used a single `$params` array; calling with named parameters throws `Unknown named parameter $model`. Upgrade: `composer require "anthropic-ai/sdk:^0.7"`
93 
94```php
95use Anthropic\Messages\RawContentBlockDeltaEvent;
96use Anthropic\Messages\TextDelta;
97 
98$stream = $client->messages->createStream(
99    model: 'claude-opus-4-7',
100    maxTokens: 64000,
101    messages: [
102        ['role' => 'user', 'content' => 'Write a haiku'],
103    ],
104);
105 
106foreach ($stream as $event) {
107    if ($event instanceof RawContentBlockDeltaEvent && $event->delta instanceof TextDelta) {
108        echo $event->delta->text;
109    }
110}
111```
112 
113---
114 
115## Tool Use
116 
117### Tool Runner (Beta)
118 
119**Beta:** The PHP SDK provides a tool runner via `$client->beta->messages->toolRunner()`. Define tools with `BetaRunnableTool` — a definition array plus a `run` closure:
120 
121```php
122use Anthropic\Lib\Tools\BetaRunnableTool;
123 
124$weatherTool = new BetaRunnableTool(
125    definition: [
126        'name' => 'get_weather',
127        'description' => 'Get the current weather for a location.',
128        'input_schema' => [
129            'type' => 'object',
130            'properties' => [
131                'location' => ['type' => 'string', 'description' => 'City and state'],
132            ],
133            'required' => ['location'],
134        ],
135    ],
136    run: function (array $input): string {
137        return "The weather in {$input['location']} is sunny and 72°F.";
138    },
139);
140 
141$runner = $client->beta->messages->toolRunner(
142    maxTokens: 16000,
143    messages: [['role' => 'user', 'content' => 'What is the weather in Paris?']],
144    model: 'claude-opus-4-7',
145    tools: [$weatherTool],
146);
147 
148foreach ($runner as $message) {
149    foreach ($message->content as $block) {
150        if ($block->type === 'text') {
151            echo $block->text;
152        }
153    }
154}
155```
156 
157### Manual Loop
158 
159Tools are passed as arrays. **The SDK uses camelCase keys** (`inputSchema`, `toolUseID`, `stopReason`) and auto-maps to the API's snake_case on the wire — since v0.5.0. See [shared tool use concepts](../shared/tool-use-concepts.md) for the loop pattern.
160 
161```php
162use Anthropic\Messages\ToolUseBlock;
163 
164$tools = [
165    [
166        'name' => 'get_weather',
167        'description' => 'Get the current weather in a given location',
168        'inputSchema' => [  // camelCase, not input_schema
169            'type' => 'object',
170            'properties' => [
171                'location' => ['type' => 'string', 'description' => 'City and state'],
172            ],
173            'required' => ['location'],
174        ],
175    ],
176];
177 
178$messages = [['role' => 'user', 'content' => 'What is the weather in SF?']];
179 
180$response = $client->messages->create(
181    model: 'claude-opus-4-7',
182    maxTokens: 16000,
183    tools: $tools,
184    messages: $messages,
185);
186 
187while ($response->stopReason === 'tool_use') {  // camelCase property
188    $toolResults = [];
189    foreach ($response->content as $block) {
190        if ($block instanceof ToolUseBlock) {
191            // $block->name  : string               — tool name to dispatch on
192            // $block->input : array<string,mixed>  — parsed JSON input
193            // $block->id    : string               — pass back as toolUseID
194            $result = executeYourTool($block->name, $block->input);
195            $toolResults[] = [
196                'type' => 'tool_result',
197                'toolUseID' => $block->id,  // camelCase, not tool_use_id
198                'content' => $result,
199            ];
200        }
201    }
202 
203    // Append assistant turn + user turn with tool results
204    $messages[] = ['role' => 'assistant', 'content' => $response->content];
205    $messages[] = ['role' => 'user', 'content' => $toolResults];
206 
207    $response = $client->messages->create(
208        model: 'claude-opus-4-7',
209        maxTokens: 16000,
210        tools: $tools,
211        messages: $messages,
212    );
213}
214 
215// Final text response
216foreach ($response->content as $block) {
217    if ($block->type === 'text') {
218        echo $block->text;
219    }
220}
221```
222 
223`$block->type === 'tool_use'` also works; `instanceof ToolUseBlock` narrows for PHPStan.
224 
225 
226---
227 
228## Extended Thinking
229 
230**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think.
231 
232```php
233use Anthropic\Messages\ThinkingBlock;
234 
235$message = $client->messages->create(
236    model: 'claude-opus-4-7',
237    maxTokens: 16000,
238    thinking: ['type' => 'adaptive'],
239    messages: [
240        ['role' => 'user', 'content' => 'Solve: 27 * 453'],
241    ],
242);
243 
244// ThinkingBlock(s) precede TextBlock in content
245foreach ($message->content as $block) {
246    if ($block instanceof ThinkingBlock) {
247        echo "Thinking:\n{$block->thinking}\n\n";
248        // $block->signature is an opaque string — preserve verbatim if
249        // passing thinking blocks back in multi-turn conversations
250    } elseif ($block->type === 'text') {
251        echo "Answer: {$block->text}\n";
252    }
253}
254```
255 
256> **Deprecated:** `['type' => 'enabled', 'budgetTokens' => N]` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above.
257 
258`$block->type === 'thinking'` also works for the check; `instanceof` narrows for PHPStan.
259 
260---
261 
262## Prompt Caching
263 
264`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`.
265 
266```php
267$message = $client->messages->create(
268    model: 'claude-opus-4-7',
269    maxTokens: 16000,
270    system: [
271        ['type' => 'text', 'text' => $longSystemPrompt, 'cacheControl' => ['type' => 'ephemeral']],
272    ],
273    messages: [['role' => 'user', 'content' => 'Summarize the key points']],
274);
275```
276 
277For 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.
278 
279Verify hits via `$message->usage->cacheCreationInputTokens` / `$message->usage->cacheReadInputTokens`.
280 
281---
282 
283## Structured Outputs
284 
285### Using StructuredOutputModel (Recommended)
286 
287Define a PHP class implementing `StructuredOutputModel` and pass it as `outputConfig`:
288 
289```php
290use Anthropic\Lib\Contracts\StructuredOutputModel;
291use Anthropic\Lib\Concerns\StructuredOutputModelTrait;
292use Anthropic\Lib\Attributes\Constrained;
293 
294class Person implements StructuredOutputModel
295{
296    use StructuredOutputModelTrait;
297 
298    #[Constrained(description: 'Full name')]
299    public string $name;
300 
301    public int $age;
302 
303    public ?string $email = null;  // nullable = optional field
304}
305 
306$message = $client->messages->create(
307    model: 'claude-opus-4-7',
308    maxTokens: 16000,
309    messages: [['role' => 'user', 'content' => 'Generate a profile for Alice, age 30']],
310    outputConfig: ['format' => Person::class],
311);
312 
313$person = $message->parsedOutput();  // Person instance
314echo $person->name;
315```
316 
317Types are inferred from PHP type hints. Use `#[Constrained(description: '...')]` to add descriptions. Nullable properties (`?string`) become optional fields.
318 
319### Raw Schema
320 
321```php
322$message = $client->messages->create(
323    model: 'claude-opus-4-7',
324    maxTokens: 16000,
325    messages: [['role' => 'user', 'content' => 'Extract: John ([email protected]), Enterprise plan']],
326    outputConfig: [
327        'format' => [
328            'type' => 'json_schema',
329            'schema' => [
330                'type' => 'object',
331                'properties' => [
332                    'name' => ['type' => 'string'],
333                    'email' => ['type' => 'string'],
334                    'plan' => ['type' => 'string'],
335                ],
336                'required' => ['name', 'email', 'plan'],
337                'additionalProperties' => false,
338            ],
339        ],
340    ],
341);
342 
343// First text block contains valid JSON
344foreach ($message->content as $block) {
345    if ($block->type === 'text') {
346        $data = json_decode($block->text, true);
347        break;
348    }
349}
350```
351 
352---
353 
354## Beta Features & Server-Side Tools
355 
356**`betas:` is NOT a param on `$client->messages->create()`** — it only exists on the beta namespace. Use it for features that need an explicit opt-in header:
357 
358```php
359use Anthropic\Beta\Messages\BetaRequestMCPServerURLDefinition;
360 
361$response = $client->beta->messages->create(
362    model: 'claude-opus-4-7',
363    maxTokens: 16000,
364    mcpServers: [
365        BetaRequestMCPServerURLDefinition::with(
366            name: 'my-server',
367            url: 'https://example.com/mcp',
368        ),
369    ],
370    betas: ['mcp-client-2025-11-20'],  // only valid on ->beta->messages
371    messages: [['role' => 'user', 'content' => 'Use the MCP tools']],
372);
373```
374 
375**Server-side tools** (bash, web_search, text_editor, code_execution) are GA and work on both paths — `Anthropic\Messages\ToolBash20250124` / `WebSearchTool20260209` / `ToolTextEditor20250728` / `CodeExecutionTool20260120` for non-beta, `Anthropic\Beta\Messages\BetaToolBash20250124` / `BetaWebSearchTool20260209` / `BetaToolTextEditor20250728` / `BetaCodeExecutionTool20260120` for beta. No `betas:` header needed for these.
376