feat(java,php): expose the http status code on the raw response

[wiebren]

Description

Linear ticket: n/a — found while running one OpenAPI document through all six SDK generators
and comparing what each one hands its caller.

withRawResponse() gives a caller the body and the headers but not the status code, so 200,
201 and 202 are indistinguishable.

That matters for any api that answers 202 Accepted when a call was taken but is still
running, and 200 OK when it is done. Plenty do: submitting an order comes back as 200 when
the store could fulfil it while you waited, and 202 when it was only queued. The body is
byte-identical in both cases — OrderResponse has no async flag — so the http status is the
entire signal. A client that cannot report it silently tells its caller the order succeeded
when it has not happened yet.

The same blindness covers 201: "created" and "here it is" are both just a body.

var response = client.orders().withRawResponse().submitOrder(id, request);
response.body();       // the order
response.headers();    // X-Job-Id
response.statusCode(); // ← did not exist: 200 or 202?

Today a caller works around it by reaching underneath the sdk — an okhttp Interceptor in
java, a psr-18 decorator in php — to record what the transport saw. Both are per-client global
state, so neither is safe when calls overlap.

Changes Made

• java — HttpResponse<T> gains statusCode() next to body() and headers(), read from
  rawResponse.code() in the constructor it is already handed. The class is a static resource
  emitted by the v1 generator and referred to by name from java-v2, so the tandem picks the
  change up in one place; java-v2's features.yml description is updated to name the new
  accessor.
• php — HttpResponse gains getStatusCode() next to getBody() and getHeaders(),
  taken from $response->getStatusCode() in HttpResponse::from. features.yml and the
  README snippet name it.
• Updated README.md generator (if applicable) — feature descriptions and the php snippet.

Both changes are additive: an existing caller of body()/getBody() or
headers()/getHeaders() sees no difference.

Stacking note. This is stacked on #17579 ("access response headers through
withRawResponse()"), which is what gives php a raw response at all, so its commit shows up
in the diff here too — review only the second one. The java half is independent of it: if you
would rather have the java accessor on its own, drop the first commit and this one still
applies.

Testing

• Unit tests added/updated
• Manual testing completed

java. ./gradlew :sdk:test :generator-utils:test passes. The generated class was then
compiled for real: a production OpenAPI document of ≈900 endpoints, generated with this
branch's generator image, builds under maven with JDK 21 — which compiles both the emitted
<Prefix>HttpResponse and every withRawResponse() call site in it.

php. The same fourteen php-sdk seed fixtures — 19/19 configurations — pass with the
scripts: composer install && composer build && composer analyze && composer test, i.e.
phpstan at level max and phpunit. exhaustive (2), pagination (3), folders (2),
unions (2), streaming, server-sent-events, multi-url-environment,
endpoint-security-auth, file-download, bytes-download, enum, unknown,
nullable-optional, response-property.

Seed snapshots are not committed here, following the auto-update-seed workflow that owns them.

End to end, against the three cases this is about. A contract suite puts the same
request/response pair to every generated client and records what each one could report. The
three status cases are the same call answered 200, 202 and 201 with an identical body;
two header cases sit next to them. ok* in that table means the client only managed it because
the runner added something the sdk does not provide.

case	java before	java after	php before	php after
sync (200)	ok* interceptor	ok	ok* psr-18 decorator	ok
async (202)	ok* interceptor	ok	ok* psr-18 decorator	ok
created (201)	ok* interceptor	ok	ok* psr-18 decorator	ok
job id on a success	ok	ok	ok*	ok
job id on an error	ok	ok	ok*	ok

Both runners were rewritten to drop their workarounds entirely — the java one no longer builds
an OkHttpClient with an interceptor, the php one no longer wraps the psr-18 client — and both
now read statusCode()/getStatusCode() off the response the sdk returns. Every row is a real
execution against a local mock api that serves the canned response of the case and records what
went over the wire.

Notes

• The status is stored at construction rather than kept as a reference to the transport
  response, so the wrapper stays independent of the http client and nothing hands out a
  half-consumed body stream.
• No new class, no new method on any client: this is one field and one accessor per language.

Generated with Claude Code

---

[nitpickybot]

AI Review Summary

Adds statusCode()/getStatusCode() to the raw response wrappers in Java and PHP, plus (from the stacked PR) the whole PHP raw-client machinery. The Java half is small and clean. In PHP a few things stand out: the raw client constructor's parameter naming is inconsistent with what the body assigns, withRawResponse() passes client options where the constructor expects environment ordering assumptions, and the README snippet is emitted unconditionally even for clients where no raw client exists.

• 🔴 1 critical issue(s)
• 🟡 3 warning(s)
• 🔵 2 suggestion(s)

---

To request another review, comment /ai-review on this pull request.

[nitpickybot]

🔴 critical

The first parameter is named $client (note the leading $ in the name, unlike the other parameters which pass bare names), but the body assigns $this->client = $${context.rawClient.getFieldName()}. If getFieldName() isn't literally client, the generated constructor references an undefined variable. Also the inconsistent $ prefix between this parameter and the ones below will produce $$environment-style names if the codegen prefixes automatically. Please make naming uniform and derive the parameter name from context.rawClient.getFieldName().

[wiebren]

Fixed (same comment on #17579). It did render correctly — php.parameter runs the name through convertToPhpVariableName, so "$client" and "client" both emit $client, and there is no $$environment case — but the spelling was inconsistent, so the parameter name and the assignment now both come from context.rawClient.getFieldName().

[nitpickybot]

🟡 warning

In the multi-URL case the constructor's second parameter is environment (required, non-optional) while in the single-URL case it's options. This helper mirrors that by position only — any future reorder in getRawClientConstructor silently breaks it. Worth extracting a single shared descriptor of the constructor's parameter list so the two can't drift.

[wiebren]

Good point, and I have removed the positional coupling entirely rather than just documenting it. Both sides are now generated from one ordered descriptor in raw-client/rawClientConstructor.ts:

interface RawClientConstructorParameter {
    parameter: php.Parameter;
    argument: php.AstNode;   // what the plain client passes
    assignment: string;      // how the raw client keeps it
}

getRawClientConstructor() maps .parameter and writes .assignment; getRawClientConstructorArguments() — used by withRawResponse() — maps .argument. A reorder moves both at once, and adding a parameter cannot be half-done.

[nitpickybot]

🟡 warning

For multi-URL clients the raw client's clientOptions is hard-coded to [], discarding the parent client's options (headers, timeouts, base overrides). Endpoint bodies read $this->{clientOptions}, so raw calls on multi-URL SDKs will behave differently from plain calls. Pass the options through here as well.

[wiebren]

Real bug, fixed. The plain root client keeps its options in the multi-url case, so resetting them to [] meant a raw root call lost the base-url override, headers, timeout and retries. Options are now always taken and always forwarded:

public function __construct(
    RawClient $client,
    Environments $environment,
    ?array $options = null,
) { ... }

// and, on the plain client:
return $this->rawResponseClient ??= new RawS3Client($this->client, $this->environment, $this->options);

[nitpickybot]

🟡 warning

ACCESS_RAW_RESPONSE_DATA snippets are added unconditionally, but the raw client is only generated when a service has endpoints. For an IR whose selected feature endpoint lives on an endpoint-less package this emits a README snippet calling a method that doesn't exist. Guard it the same way the generators do (service.endpoints.length > 0).

[wiebren]

I do not think this case can arise. getEndpointsForFeature resolves to real endpoints — the ones configured in readmeConfig.features, or [this.defaultEndpointId] — and an endpoint always belongs to a service, so the client the snippet addresses has at least one endpoint and therefore has a raw client. There is no path where an endpoint id maps to an endpoint-less package.

This also matches how the neighbouring snippet builders work: buildExceptionHandlingSnippets, buildRetrySnippets and buildTimeoutSnippets are all emitted unconditionally off the same helper. Happy to add a guard anyway if you can point at an IR shape where it breaks.

[nitpickybot]

🔵 suggestion

getHeader is O(n) per lookup over all headers. Fine for typical header counts, but if you want case-insensitive lookup cheaply, build a lowercased index once in the constructor. Not blocking.

[wiebren]

Fair, and deliberate — a lowercased index would mean building and holding a second array on every response for a lookup over what is typically a handful of headers, and getHeaders() has to keep the original casing anyway. Left as the linear scan; happy to revisit if a profile ever says otherwise.

[nitpickybot]

🔵 suggestion

$this->headers = $headers is assigned before parent::__construct(...). Harmless here, but conventionally the parent constructor runs first; keeping the order consistent avoids surprises if the base class ever touches subclass state.

[wiebren]

This matches the constructor that is already generated — $this->body = $body; is likewise assigned before parent::__construct(...) — so putting the headers first keeps the two adjacent instead of splitting them around the parent call. Reordering both would change output that is not part of this change. The base class is Exception via the generated base exception, which does not read subclass state.

[devin-ai-integration]

Devin Review found 1 potential issue.

1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

[devin-ai-integration]

🟡 Raw responses disappear behind interfaces

When generateClientInterfaces is enabled, the generated interfaces omit withRawResponse(). Consumers typed against those interfaces cannot access any response metadata.

Prompt for agents

Add withRawResponse() signatures to both generated client-interface variants when their corresponding service has endpoints. Update RootClientInterfaceGenerator and SubPackageClientInterfaceGenerator so the interface contract matches the new public methods emitted by RootClientGenerator and SubPackageClientGenerator, using the appropriate raw root or raw subpackage return type. Cover generateClientInterfaces configurations for root and nested service clients.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[wiebren]

Implemented. RootClientInterfaceGenerator and SubPackageClientInterfaceGenerator now declare withRawResponse() whenever the service has endpoints, returning the concrete raw client — the shape java and go use. The folders:with-interfaces fixture passes with the scripts (phpstan at level max and phpunit); the five interfaces with endpoints gained the method.