1# Tool Use — PHP
2 
3For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md).
4 
5## Tool Use
6 
7### Tool Runner (Beta)
8 
9**Beta:** The PHP SDK provides a tool runner via `$client->beta->messages->toolRunner()`. Define tools with `BetaRunnableTool` — a definition array plus a `run` closure:
10 
11```php
12use Anthropic\Lib\Tools\BetaRunnableTool;
13 
14$weatherTool = new BetaRunnableTool(
15    definition: [
16        'name' => 'get_weather',
17        'description' => 'Get the current weather for a location.',
18        'inputSchema' => [
19            'type' => 'object',
20            'properties' => [
21                'location' => ['type' => 'string', 'description' => 'City and state'],
22            ],
23            'required' => ['location'],
24        ],
25    ],
26    run: function (array $input): string {
27        return "The weather in {$input['location']} is sunny and 72°F.";
28    },
29);
30 
31$runner = $client->beta->messages->toolRunner(
32    maxTokens: 16000,
33    messages: [['role' => 'user', 'content' => 'What is the weather in Paris?']],
34    model: 'claude-opus-4-8',
35    tools: [$weatherTool],
36);
37 
38foreach ($runner as $message) {
39    foreach ($message->content as $block) {
40        if ($block->type === 'text') {
41            echo $block->text;
42        }
43    }
44}
45```
46 
47### Manual Loop
48 
49Tools 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.
50 
51```php
52use Anthropic\Messages\ToolUseBlock;
53 
54$tools = [
55    [
56        'name' => 'get_weather',
57        'description' => 'Get the current weather in a given location',
58        'inputSchema' => [  // camelCase, not input_schema
59            'type' => 'object',
60            'properties' => [
61                'location' => ['type' => 'string', 'description' => 'City and state'],
62            ],
63            'required' => ['location'],
64        ],
65    ],
66];
67 
68$messages = [['role' => 'user', 'content' => 'What is the weather in SF?']];
69 
70$response = $client->messages->create(
71    model: 'claude-opus-4-8',
72    maxTokens: 16000,
73    tools: $tools,
74    messages: $messages,
75);
76 
77while ($response->stopReason === 'tool_use') {  // camelCase property
78    $toolResults = [];
79    foreach ($response->content as $block) {
80        if ($block instanceof ToolUseBlock) {
81            // $block->name  : string               — tool name to dispatch on
82            // $block->input : array<string,mixed>  — parsed JSON input
83            // $block->id    : string               — pass back as toolUseID
84            $result = executeYourTool($block->name, $block->input);
85            $toolResults[] = [
86                'type' => 'tool_result',
87                'toolUseID' => $block->id,  // camelCase, not tool_use_id
88                'content' => $result,
89            ];
90        }
91    }
92 
93    // Append assistant turn + user turn with tool results
94    $messages[] = ['role' => 'assistant', 'content' => $response->content];
95    $messages[] = ['role' => 'user', 'content' => $toolResults];
96 
97    $response = $client->messages->create(
98        model: 'claude-opus-4-8',
99        maxTokens: 16000,
100        tools: $tools,
101        messages: $messages,
102    );
103}
104 
105// Final text response
106foreach ($response->content as $block) {
107    if ($block->type === 'text') {
108        echo $block->text;
109    }
110}
111```
112 
113`$block->type === 'tool_use'` also works; `instanceof ToolUseBlock` narrows for PHPStan.
114 
115 
116---
117 
118## Structured Outputs
119 
120### Using StructuredOutputModel (Recommended)
121 
122Define a PHP class implementing `StructuredOutputModel` and pass it as `outputConfig`:
123 
124```php
125use Anthropic\Lib\Contracts\StructuredOutputModel;
126use Anthropic\Lib\Concerns\StructuredOutputModelTrait;
127use Anthropic\Lib\Attributes\Constrained;
128 
129class Person implements StructuredOutputModel
130{
131    use StructuredOutputModelTrait;
132 
133    #[Constrained(description: 'Full name')]
134    public string $name;
135 
136    public int $age;
137 
138    public ?string $email = null;  // nullable = optional field
139}
140 
141$message = $client->messages->create(
142    model: 'claude-opus-4-8',
143    maxTokens: 16000,
144    messages: [['role' => 'user', 'content' => 'Generate a profile for Alice, age 30']],
145    outputConfig: ['format' => Person::class],
146);
147 
148$person = $message->parsedOutput();  // Person instance
149echo $person->name;
150```
151 
152Types are inferred from PHP type hints. Use `#[Constrained(description: '...')]` to add descriptions. Nullable properties (`?string`) become optional fields.
153 
154### Raw Schema
155 
156```php
157$message = $client->messages->create(
158    model: 'claude-opus-4-8',
159    maxTokens: 16000,
160    messages: [['role' => 'user', 'content' => 'Extract: John ([email protected]), Enterprise plan']],
161    outputConfig: [
162        'format' => [
163            'type' => 'json_schema',
164            'schema' => [
165                'type' => 'object',
166                'properties' => [
167                    'name' => ['type' => 'string'],
168                    'email' => ['type' => 'string'],
169                    'plan' => ['type' => 'string'],
170                ],
171                'required' => ['name', 'email', 'plan'],
172                'additionalProperties' => false,
173            ],
174        ],
175    ],
176);
177 
178// First text block contains valid JSON
179foreach ($message->content as $block) {
180    if ($block->type === 'text') {
181        $data = json_decode($block->text, true);
182        break;
183    }
184}
185```
186 
187---
188 
189## Beta Features & Anthropic-Defined Tools
190 
191**`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:
192 
193```php
194use Anthropic\Beta\Messages\BetaRequestMCPServerURLDefinition;
195 
196$response = $client->beta->messages->create(
197    model: 'claude-opus-4-8',
198    maxTokens: 16000,
199    mcpServers: [
200        BetaRequestMCPServerURLDefinition::with(
201            name: 'my-server',
202            url: 'https://example.com/mcp',
203        ),
204    ],
205    betas: ['mcp-client-2025-11-20'],  // only valid on ->beta->messages
206    messages: [['role' => 'user', 'content' => 'Use the MCP tools']],
207);
208```
209 
210### Task budgets
211 
212```php
213$response = $client->beta->messages->create(
214    model: 'claude-opus-4-8',
215    maxTokens: 16000,
216    outputConfig: ['taskBudget' => ['type' => 'tokens', 'total' => 64000]],
217    tools: [...],
218    messages: [...],
219    betas: ['task-budgets-2026-03-13'],
220);
221```
222 
223### Cache diagnostics
224 
225Pass the previous response's `id` on the next request; print the `diagnostics` object on the response:
226 
227```php
228$r2 = $client->beta->messages->create(
229    model: 'claude-opus-4-8', maxTokens: 1024,
230    diagnostics: ['previousMessageId' => $r1->id],
231    betas: ['cache-diagnosis-2026-04-07'],
232    messages: [...],
233);
234```
235 
236**Anthropic-defined tools** (bash, web_search, text_editor, code_execution) are GA and work on both paths. Of these, web_search and code_execution are server-executed; bash and text_editor are client-executed (you handle the `tool_use` locally) — `Anthropic\Messages\ToolBash20250124` / `WebSearchTool20260209` / `ToolTextEditor20250728` / `CodeExecutionTool20260120` for non-beta, `Anthropic\Beta\Messages\BetaToolBash20250124` / `BetaWebSearchTool20260209` / `BetaToolTextEditor20250728` / `BetaCodeExecutionTool20260120` for beta. No `betas:` header needed for these.
237 
238### Tool search (non-beta, server-side)
239 
240```php
241tools: [
242    ['type' => 'tool_search_tool_regex_20251119', 'name' => 'tool_search_tool_regex'],
243    ['name' => 'get_weather', 'description' => '...', 'inputSchema' => [...], 'deferLoading' => true],
244    // ... other user tools with 'deferLoading' => true
245],
246```
247 
248### Memory tool (non-beta, client-executed)
249 
250Declare `['type' => 'memory_20250818', 'name' => 'memory']`. Handle the `tool_use` by reading/writing files under a fixed `/memories` directory. **Validate every model-supplied path**: resolve to its canonical form and verify it remains within the memory directory; reject traversal (`..`, symlinks) — see `shared/tool-use-concepts.md` § Client-Side Tools.
251 
252---
253 
254