feat(php): add SSE / NDJSON / text streaming support

[patrickthornton]

Closes FER-10530.

Summary

Adding PHP streaming support to match Python/Java/Go/etc.

Generated PHP SDKs now emit real streaming methods for endpoints with a response-stream instead of broken void methods that always throw. SSE, NDJSON, and raw text streaming all dispatch through a single unified Stream<T> runtime helper (Go's strategy from internal/streamer.go) with thin SseStream / JsonStream / TextStream wrappers for clean named return types.

What gets generated

For each response-stream endpoint, the generator picks the format from the IR's StreamingResponse union (sse / json / text) and emits a method whose return type is one of the three wrappers below. All three share a buffer-cap and BOM-safe line reader; the differences are framing and constructor signature.

SSE — SseStream<T>

Interface

final class SseStream<T> extends Stream<T>
{
    public function __construct(
        ResponseInterface $response,
        Closure $deserializer,                // fn(string $data): T
        ?string $terminator = '[DONE]',       // null disables terminator handling
        int $maxBufferSize = 1_048_576,       // 1 MiB cap on buffered data
    );

    /** @return Generator<int, T>           — yields payloads only (foreach) */
    public function getIterator(): Generator;

    /** @return Generator<int, SseEvent<T>> — yields payload + WHATWG metadata */
    public function events(): Generator;
}

final class SseEvent<T>
{
    public readonly T       $data;     // deserialized payload
    public readonly string  $event;    // `event:` field, '' if absent
    public readonly string  $id;       // last `id:` (persists per WHATWG)
    public readonly ?int    $retry;    // `retry:` ms, or null
}

Validates Content-Type: text/event-stream and rejects non-UTF-8 charsets. Handles multi-line data: (newline-joined), comment lines (: prefix), CRLF/CR normalization, and leading-space stripping per WHATWG §9.2.

Generated method

public function subscribe(?array $options = null): SseStream
{
    // ... sends request, captures $statusCode ...
    if ($statusCode >= 200 && $statusCode < 400) {
        return new SseStream(
            response: $response,
            deserializer: fn (string $data) => EventStreamResponse::fromJson($data),
            terminator: null,
        );
    }
    throw new Auth0ApiException(...);
}

Consumer usage

// Data-only iteration:
foreach ($auth0->events->subscribe() as $event) {
    match ($event->getType()) {
        'user.created' => handleUserCreated($event->getValue()),
        'offset-only'  => updateCursor($event->getValue()->getOffset()),
        default        => null,
    };
}

// With SSE metadata (event type, id for resume, retry hint):
foreach ($auth0->events->subscribe()->events() as $sse) {
    echo "event={$sse->event} id={$sse->id}\n";
    handlePayload($sse->data);
}

NDJSON — JsonStream<T>

Interface

final class JsonStream<T> extends Stream<T>
{
    public function __construct(
        ResponseInterface $response,
        Closure $deserializer,                // fn(string $line): T
        ?string $terminator = null,           // optional sentinel line
        int $maxBufferSize = 1_048_576,
    );

    /** @return Generator<int, T> */
    public function getIterator(): Generator;
}

One JSON document per line. Empty lines are skipped; a terminator line (if set) ends iteration cleanly.

Generated method

public function generateStream(GenerateStreamRequest $request, ?array $options = null): JsonStream
{
    // ... sends request, captures $statusCode ...
    if ($statusCode >= 200 && $statusCode < 400) {
        return new JsonStream(
            response: $response,
            deserializer: fn (string $data) => StreamResponse::fromJson($data),
            terminator: null,
        );
    }
    throw new SeedApiException(...);
}

Consumer usage

foreach ($client->dummy->generateStream($req) as $chunk) {
    echo $chunk->getId() . "\n";
}

Plain text — TextStream

Interface

final class TextStream extends Stream<string>
{
    public function __construct(
        ResponseInterface $response,
        int $maxBufferSize = 1_048_576,
    );

    /** @return Generator<int, string> */
    public function getIterator(): Generator;
}

No deserializer — yields each line of the response body as a raw string. CRLF/CR normalized to LF; UTF-8 BOM stripped if present.

Generated method

public function tail(?array $options = null): TextStream
{
    // ... sends request, captures $statusCode ...
    if ($statusCode >= 200 && $statusCode < 400) {
        return new TextStream(response: $response);
    }
    throw new SeedApiException(...);
}

Consumer usage (illustrative — no current fixture exercises text streaming end-to-end, but the codegen path is identical to NDJSON minus the deserializer)

foreach ($client->logs->tail() as $line) {
    echo $line . "\n";
}

Implementation

• New runtime helper Stream.Template.php emitted into every generated SDK with streaming endpoints, plus thin SseStream / JsonStream / TextStream wrappers and an SseEvent<T> envelope for the metadata path.
• IR's existing StreamingResponse._visit({ sse, json, text }) is now consumed by both the return-type generator and the success-branch emitter; no IR change needed.
• Gated on ir.sdkConfig.hasStreamingEndpoints so SDKs without streaming endpoints are unaffected.
• 13 new PHPUnit cases in StreamTest.Template.php covering the WHATWG SSE spec corners (multi-line data:, comment lines, CRLF, terminator, charset validation) plus JSON/text framing.

Test plan

• pnpm seed test --generator php-sdk --fixture streaming — passes, NDJSON output now emits JsonStream<StreamResponse>.
• pnpm seed test --generator php-sdk --fixture streaming-parameter — passes.
• pnpm seed test --generator php-sdk --fixture server-sent-events — passes, emits SseStream<StreamedCompletion>.
• pnpm seed test --generator php-sdk --fixture server-sent-events-openapi — passes (removed from allowedFailures).
• pnpm seed test --generator php-sdk --fixture server-sent-event-examples — passes.
• PHPStan and PHPUnit clean on regenerated seed/php-sdk/server-sent-events (65 tests, 233 assertions).
• Manually generated Auth0's PHP SDK and verified EventsClient::subscribe() now produces a real SSE method. Wrote an integration test exercising MockHttpClient → RawClient → EventsClient::subscribe() → SseStream → discriminated-union dispatch; all 4 cases pass.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[github-actions]

SDK Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-05-14T05:16:07Z).

Full benchmark table (click to expand)

Generator	Spec	main (generator)	main (E2E)	PR (generator)	Delta
php-sdk	square	56s (n=5)	77s (n=5)	52s	-4s (-7.1%)

main (generator): generator-only time via --skip-scripts (includes Docker image build, container startup, IR parsing, and code generation — this is the same Docker-based flow customers use via fern generate). main (E2E): full customer-observable time including build/test scripts (nightly baseline, informational). Delta is computed against generator-only baseline.
⚠️ = generation exited with a non-zero exit code (timing may not reflect a successful run).
Baseline from nightly runs on main (latest: 2026-05-14T05:16:07Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-05-14 15:40 UTC

[iamnamananand996]

Looking at the seeds looks good