Calling the Claude API from Symfony: streaming, structured extraction, and per-plan quotas

Adding "AI features" to a SaaS in 2026 is table stakes. Adding them well — streaming that doesn't buffer, costs that can't run away, a test suite that doesn't need an API key — is where most integrations fall short. This is the architecture I built for ShipAnvil's AI module, and the decisions behind it.

SDK or no SDK?

Anthropic ships an official PHP SDK (anthropic-ai/sdk), and it's a fine choice. I deliberately went the other way: the Claude API is one JSON endpoint (POST /v1/messages with x-api-key and anthropic-version headers), and Symfony's HttpClient already does everything needed — scoped clients, retries, timeouts, streaming. Owning the ~300 lines means you own every byte on the wire, your retry policy is your retry policy, and there's one less dependency at the very bottom of your product. For a boilerplate whose buyers will read and modify the code, that transparency is the feature. If you'd rather not own it, swap the implementation behind the same interface — that's what the interface is for.

# config/packages/framework.yaml
framework:
    http_client:
        scoped_clients:
            anthropic.client:
                base_uri: 'https://api.anthropic.com'
                headers:
                    x-api-key: '%env(ANTHROPIC_API_KEY)%'
                    anthropic-version: '2023-06-01'
                timeout: 120   # generous: thinking models take their time

Decision 1: an interface, and a fake that actually behaves

Everything depends on AiClientInterface (complete() + stream()), with two implementations: the real Anthropic client and an offline deterministic stub. The stub isn't a mock that returns "ok" — it streams plausible chunks with realistic timing and "extracts" real-looking structures. That buys you:

• Tests without keys or network. The whole AI feature surface runs in CI, deterministic and free.
• Development without burning tokens. Front-end work on the chat UI doesn't need a live model.
• A product you can demo and sell without AI configured — flip one env var to go live.

Decision 2: parse SSE incrementally, forward it incrementally

With "stream": true, the Messages API answers with Server-Sent Events: message_start, then content_block_delta events carrying text_delta chunks, then message_stop. Two things go wrong in naive implementations:

Buffering. HttpClient gives you raw chunks; an SSE event can span several chunks or arrive several-per-chunk. You need a small incremental parser that buffers on \n\n boundaries and yields complete events — not a regex over the full body at the end (that's not streaming, that's waiting with extra steps).

foreach ($this->httpClient->stream($response) as $chunk) {
    foreach ($this->sseParser->push($chunk->getContent()) as $event) {
        if ('content_block_delta' === $event->type) {
            yield $event->textDelta();   // a few characters, immediately
        }
    }
}

The last hop. Your beautifully streamed tokens then hit a controller that buffers the whole response anyway. Use a StreamedResponse, disable output buffering, and check your reverse proxy: with Apache + PHP-FPM, X-Accel-Buffering: no and flushing after each chunk is the difference between "typewriter effect" and "30-second pause, then a wall of text".

Decision 3: structured extraction via tool use, not "please reply in JSON"

For anything that feeds program logic — extracting contacts, classifying tickets, parsing documents — don't prompt for JSON and json_decode your fingers crossed. Define a tool whose input_schema is the structure you want, and force it with tool_choice:

$payload = [
    'model' => $this->model,
    'max_tokens' => 1024,
    'messages' => [['role' => 'user', 'content' => $text]],
    'tools' => [[
        'name' => 'save_contact',
        'description' => 'Record the contact details found in the text.',
        'input_schema' => [
            'type' => 'object',
            'properties' => [
                'name' => ['type' => 'string'],
                'email' => ['type' => 'string'],
                'company' => ['type' => 'string'],
            ],
            'required' => ['name'],
        ],
    ]],
    'tool_choice' => ['type' => 'tool', 'name' => 'save_contact'],
];

The model must respond with a tool_use block whose input matches your schema — you get a parsed array, not prose that usually contains JSON. Wrap this in a small StructuredExtractor service and every future "turn this text into data" feature is a schema definition away. (The API also has a first-class structured-outputs mode via output_config — same idea, worth evaluating; tool use has the advantage of working uniformly across model generations.)

Decision 4: meter usage where billing already lives

The failure mode of AI features isn't technical, it's economic: one enthusiastic user on your 9 €/month plan can spend more in tokens than their subscription. The fix is to treat AI usage like any other entitlement:

• Every completed request writes an AiUsage row (organization, feature, input/output tokens — the API returns exact counts in usage).
• A quota check runs before each request, against limits defined in the same plan configuration as the rest of billing — not in a second config that drifts.
• When the quota's gone, the user gets a clean "you've used this month's AI allowance — upgrade?" — which makes AI a reason to upgrade, the only sane way to price it.

Tie the metering to the organization, not the user, for the same reason subscriptions attach there: teams share a plan, so they share its allowance.

Decision 5: retries with backoff, but never on POST-that-succeeded

The API returns 429 on rate limits and 529 when overloaded — both retryable with exponential backoff and jitter. Two subtleties: respect the retry-after header when present, and only retry when you know the request didn't produce a billable completion (connection failures, 4xx-before-processing, explicit overload signals). A blind retry-on-5xx policy around a streaming response can double-bill a long completion that failed at the last byte.

Model choice, as of June 2026: claude-opus-4-8 as the capable default, claude-sonnet-4-6 for the speed/cost sweet spot on production traffic, claude-haiku-4-5 for cheap high-volume tasks. Make it an env var — model IDs change more often than your code should (current list).

The shape of the whole thing

src/Ai/
├── Client/        AiClientInterface, AnthropicClient, FakeAiClient, SseEventParser
├── Extraction/    StructuredExtractor + your schemas
├── Quota/         per-plan limits, usage metering
└── Controller/    streaming chat, extraction endpoints

That module — streaming chat UI included, quotas pre-wired into the billing plans, the fake provider, and the tests for all of it — ships in ShipAnvil alongside the billing it plugs into. You can try the chat in the live demo — it runs on the offline stub, which is rather the point.