Chapter 03 · Beginner
Your First Claude Request in PHP
Make your first Claude API call in PHP with the community SDK or Guzzle, read the response, and diagnose common request errors.

Lesson artwork

Overview
Section titled “Overview”Send a text request to Claude with the community Claude-PHP-SDK, then make the same kind of request directly over HTTP with Guzzle. You’ll read text blocks and token counts, parse JSON supplied by the model, and diagnose failed requests.
Prerequisites
Section titled “Prerequisites”- PHP 8.6 and Composer
- An Anthropic API key from Chapter 02
- A local copy of the Chapter 03 examples
Step 1: Installation and Project Setup
Section titled “Step 1: Installation and Project Setup”From the repository root, open the chapter directory and install its dependencies.
cd code/claude-php/chapter-03composer installcp .env.example .envSet ANTHROPIC_API_KEY in .env or export it from your shell. Keep .env out of version control. ANTHROPIC_MODEL defaults to claude-sonnet-5-5. Use a model ID available to your account if you need to change it. Claude model lifecycle
Step 2: Your First Claude API Request
Section titled “Step 2: Your First Claude API Request”php examples/sdk-request.phpThe script loads the key and model from the chapter’s bootstrap.php. Here is the request at its core.
<?php
declare(strict_types=1);
use ClaudePhp\ClaudePhp;
$config = require __DIR__ . '/../bootstrap.php';$client = new ClaudePhp(apiKey: $config['apiKey']);
$response = $client->messages()->create([ 'model' => $config['model'], 'max_tokens' => 256, 'system' => 'Answer in one concise sentence.', 'messages' => [ ['role' => 'user', 'content' => 'What is Composer used for in PHP?'], ],]);
foreach ($response->content as $block) { if ($block['type'] === 'text') { echo $block['text'] . PHP_EOL; }}
printf("Tokens: %d in, %d out\n", $response->usage->input_tokens, $response->usage->output_tokens);Expect a sentence about dependency management followed by input and output token counts. The wording and token counts vary by request. The community SDK accepts a single associative array with snake_case API fields. Its message response has object properties, with an array of content blocks.
Anthropic also publishes a PHP SDK under anthropic-ai/sdk. Its examples use Anthropic\Client and a different method signature. Anthropic PHP SDK reference
Step 3: Understanding Request Parameters
Section titled “Step 3: Understanding Request Parameters”| Field | Purpose |
|---|---|
model | Selects the Claude model for the request. |
max_tokens | Caps the generated output. Check stop_reason for max_tokens if output is cut short. |
messages | Supplies an ordered conversation using user and assistant turns. |
system | Gives instructions for the entire request. |
stop_sequences | Supplies optional strings that end generation when encountered, where supported by the selected model. |
The Messages API is stateless. For a follow-up, send the needed history along with the next user turn. Separate the system instructions from that history.
<?php
$conversation = [ ['role' => 'user', 'content' => 'What does Composer do?'], ['role' => 'assistant', 'content' => 'It manages PHP dependencies and autoloading.'], ['role' => 'user', 'content' => 'What does composer.lock record?'],];The examples use prompt instructions to control style and format. Check model support before adding sampling parameters such as temperature or top_p. Messages API reference
Building Requests with the Builder Pattern
Section titled “Building Requests with the Builder Pattern”Start with an associative array for a single call. As requests become more dynamic, centralise required fields and defaults, then change only what each caller needs. This example uses a function as the smallest reusable request builder.
<?php
declare(strict_types=1);
function buildMessageRequest(string $model, string $prompt, int $maxTokens = 256): array{ if (trim($prompt) === '' || $maxTokens < 1) { throw new InvalidArgumentException('Supply a prompt and a positive token limit.'); }
return [ 'model' => $model, 'max_tokens' => $maxTokens, 'messages' => [['role' => 'user', 'content' => $prompt]], ];}Pass the array to $client->messages()->create(). A builder class becomes useful when several components contribute the model, system prompt, or conversation history.
Make the Request with Guzzle
Section titled “Make the Request with Guzzle”php examples/guzzle-request.phpThe script sends the same JSON field names to POST /v1/messages. Guzzle’s json option encodes the payload and sets Content-Type: application/json. The client adds x-api-key and anthropic-version to the request.
The sample sets a five-second connection timeout and a 30-second request timeout. On success, json_decode() returns an associative array, so access the content with $message['content']. Longer work may need a larger timeout or streaming, which Chapter 16 covers.
Parsing Responses
Section titled “Parsing Responses”An API response can contain several content blocks. Collect blocks whose type is text and inspect stop_reason to learn why generation ended.
Extracting JSON from Responses
Section titled “Extracting JSON from Responses”php examples/response-parsing.phpThe script asks for one JSON object, collects the text blocks, and strips a surrounding Markdown fence if present. It checks that the decoded object contains two string fields. Successful output looks like this.
Composer: Manages dependencies in a PHP project.The model can still produce malformed JSON or a different shape. Catch JsonException, validate fields before use, and check for truncation when a request reaches its output limit. Use Claude’s structured outputs when your application needs a schema guarantee.
Working with a Response in Your Application
Section titled “Working with a Response in Your Application”Keep API-specific fields at the boundary. A service can return its own response value with just the fields callers need, such as the text, model, stop reason, and token counts. Use the returned model and input and output token counts with their separate per-million-token prices to estimate cost. Features such as prompt caching may add separate usage and pricing fields. Claude pricing
The community SDK exposes the status and request ID on ClaudePhp\Exceptions\APIStatusError. Guzzle raises a RequestException for HTTP errors. Record the status and request ID for diagnosis. Keep API keys and request content out of shared logs.
| Result | What to check |
|---|---|
400 Bad Request | Verify parameter names, message shape, and support for model-specific options. |
401 Unauthorized | Check the key in .env or the shell environment. |
403 Forbidden or 404 Not Found | Check account access, the model ID, and the request path. |
429 Too Many Requests | Respect retry-after when supplied and reduce request concurrency. |
Timeout, 500, or 529 | Check the network or service status. For transient failures, retry with capped backoff and jitter. |
A request that times out may have reached Claude. Before retrying automatically, account for possible duplicate work or charges. For rate limits, start with the API’s rate-limit guide.
Request Debugging and HTTP Configuration
Section titled “Request Debugging and HTTP Configuration”For diagnostics, log the HTTP status, the response’s request-id header when present, and elapsed time. Avoid logging API keys, complete prompts, or user data. Use a shared client for requests in the same process so its transport can reuse connections.
You can pass a configured Guzzle client as the community SDK’s httpClient. This lets you choose timeouts and supply a mock client in tests.
<?php
declare(strict_types=1);
use ClaudePhp\ClaudePhp;use GuzzleHttp\Client;
$config = require __DIR__ . '/../bootstrap.php';$httpClient = new Client(['connect_timeout' => 5.0, 'timeout' => 30.0]);$claude = new ClaudePhp(apiKey: $config['apiKey'], httpClient: $httpClient);For short requests, set a timeout that fits your application’s response budget. For longer generation, use streaming and account for partial output if the connection closes.
Exercises
Section titled “Exercises”- Add a system instruction to change the answer style, then compare output token counts.
- Send a two-turn conversation using the same SDK call and return only the new answer.
- Try a response with an unexpected JSON field type and verify that your validation rejects it.
Next Steps
Section titled “Next Steps”Continue with Chapter 04: Understanding Messages and Conversations to build multi-turn requests.