Chapter 16 · Intermediate
The Claude PHP SDK
Stream Claude responses with the community PHP SDK and use Guzzle to test request and response middleware without an API key.

Lesson artwork

Overview
Section titled “Overview”Use the community Claude-PHP-SDK to stream text from Claude. Then use a Guzzle transport to add application middleware, record token usage, and test the Messages request with a fake response.
The Composer package claude-php/claude-php-sdk provides ClaudePhp\ClaudePhp, the client used throughout these examples. Anthropic’s official PHP SDK is the separate package anthropic-ai/sdk, which provides Anthropic\Client. Each package documents its own request and response types. Community SDK · Anthropic PHP SDK
Prerequisites
Section titled “Prerequisites”Use PHP 8.6, Composer, and a local copy of the Chapter 16 examples. Review Chapter 03 for basic request and response handling.
Installing the SDK
Section titled “Installing the SDK”From the repository root, install the chapter’s Composer dependencies. The mock examples work immediately.
cd code/claude-php/chapter-16composer installphp examples/custom-transport.phpphp examples/testing.phpThe first command that runs PHP prints Mocked response. The second checks the method, path, headers, request payload, middleware order, and response content.
For live examples, copy .env.example to .env and provide ANTHROPIC_API_KEY. The examples use ANTHROPIC_MODEL if you set it.
Streaming Responses
Section titled “Streaming Responses”php examples/stream.phpmessages()->stream() takes the same array of request parameters as messages()->create(). It returns an iterable of decoded server-sent events. Set Guzzle’s stream option to let the SDK read the HTTP response incrementally. Below is the text handling from the sample.
<?php
declare(strict_types=1);
use ClaudePhp\ClaudePhp;use GuzzleHttp\Client;
$config = require __DIR__ . '/../bootstrap.php';$transport = new Client(['stream' => true, 'timeout' => 60.0]);$client = new ClaudePhp(apiKey: $config['apiKey'], httpClient: $transport);
$stream = $client->messages()->stream([ 'model' => $config['model'], 'max_tokens' => 256, 'messages' => [['role' => 'user', 'content' => 'Explain dependency injection in one sentence.']],]);
try { foreach ($stream as $event) { if ($event['type'] === 'error') { throw new RuntimeException('Claude sent a stream error.'); }
if ($event['type'] === 'content_block_delta' && $event['delta']['type'] === 'text_delta') { echo $event['delta']['text']; flush(); } }} finally { $stream->close();}The downloadable script also checks for the message_stop event so it can report an incomplete response. Keep that check when saving the output as a finished message. Web servers and proxies can buffer output, so verify streaming end to end if you use it in a browser. Claude streaming events
Middleware and Custom Transport
Section titled “Middleware and Custom Transport”The chapter’s SDKWrapper uses Guzzle to send JSON directly to the Messages API. Each registered middleware function sees the request payload before sending and the decoded response after it returns. Return the data from each callback so the next callback receives it.
<?php
declare(strict_types=1);
use ClaudePHP\SDK\SDKWrapper;
$config = require __DIR__ . '/../bootstrap.php';$client = new SDKWrapper($config['apiKey']);
$client->addMiddleware(static function (string $phase, array $data): array { if ($phase === 'response') { printf("Output tokens: %d\n", $data['usage']['output_tokens']); }
return $data;});
$client->sendMessage([ 'model' => $config['model'], 'max_tokens' => 256, 'messages' => [['role' => 'user', 'content' => 'What is middleware?']],]);Run php examples/middleware.php to aggregate token usage over two requests. Run php examples/sdk-advanced.php to log the model and response ID. Logging identifiers and counts is usually sufficient to correlate failures without recording API keys or prompts.
Testing with a Mock Response
Section titled “Testing with a Mock Response”examples/testing.php injects a GuzzleHttp\Client backed by MockHandler. The queued response contains the same text and usage fields as the live endpoint, and Guzzle’s history middleware saves the outgoing request for inspection. This runs the wrapper and its middleware locally.
Try changing the expected token count in the test and rerun it. The script reports a failure and exits with a nonzero status. Restore the expected value to see the pass result.
Troubleshooting
Section titled “Troubleshooting”- If Composer cannot load
ClaudePhp\ClaudePhp, runcomposer installfrom the Chapter 16 directory and confirmcomposer show claude-php/claude-php-sdk. - For authentication errors, verify the key in the chapter’s
.envand check whether your shell already exports a different key. - If the stream ends early, handle the text as partial output and investigate the network or response error before retrying.
Continue to Chapter 17: Building a Claude Service Class to apply these patterns in a reusable service.