Changelog

(fix): Send request bodies declared with the application/x-www-form-urlencoded content type (e.g. OAuth token endpoints) as form-urlencoded instead of JSON. A new UrlEncodedApiRequest core type encodes the body with http_build_query and sets the Content-Type: application/x-www-form-urlencoded header.

(fix): Wire OAuth client-credentials authentication into the root client when the OAuth scheme is not the first scheme in the API’s auth configuration (e.g. auth: any with basic auth listed before OAuth). Previously the OAuth token provider was only generated when OAuth was the first auth scheme, so the root client silently fell back to the other schemes and never used the OAuth credentials. When both an OAuth and an inferred auth scheme are present, the provider-based scheme that appears first in the auth configuration is used.

(feat): Auto-generation of the idempotency key header is now driven by the IR (sdkConfig.idempotencyKeyGeneration) instead of a generator config flag. When enabled, retry-unsafe requests (the IR-configured eligible methods, POST/PUT by default) attach the configured header (default Idempotency-Key) with a freshly generated UUIDv4 unless the caller supplies one. The header name and eligible methods come from the IR so behavior is consistent across generators.

(feat): Add support for server URL variables (e.g. region/edge routing). Server variables defined on the API’s environments are now exposed as optional string parameters on the client constructor and interpolated into the base URL(s) at construction time, falling back to each variable’s default when not provided. Conflicting constructor option names are de-collided with a serverUrl prefix and numeric suffix when needed (e.g. a variable named environment is exposed as serverUrlEnvironment).

(chore): Upgrade the PHP SDK generator to consume IR v67.

(fix): Normalize the architecture label in the structured User-Agent (emitted when includePlatformHeaders is enabled) so the 64-bit x86 aliases (x64, amd64, x86_64) all report as the canonical x86_64, keeping the value consistent across generators.

(feat): Add opt-in support for a structured User-Agent header on generated SDK clients, gated behind a new includePlatformHeaders config option (default off, so existing generated output is unchanged). When enabled, the client reports its SDK name/version plus the operating system, architecture, and PHP runtime version in the Twilio-style shape {sdkName}/{sdkVersion} ({os}; {arch}) PHP/{runtimeVersion} (e.g. my-sdk/1.0.0 (linux; x86_64) PHP/8.2.0). The platform values are resolved at runtime via PHP_OS, php_uname('m'), and PHP_VERSION. Unknown segments are omitted gracefully (the (os; arch) group is dropped when both are empty, a single known value is included on its own, and the version suffix is dropped when unavailable), and the discrete X-Fern-Platform / X-Fern-Runtime headers are consolidated into the User-Agent.

(fix): Make each scheme’s credentials optional under any-composed auth. Previously, with a multi-scheme auth: any: [...] config the generated client treated OAuth (and other) credentials as unconditionally required at construction, so a caller who only wanted API-key auth could not instantiate the client. Credentials now fall back to environment variables without throwing, and the OAuth/inferred token provider and auth headers are only set up when that scheme’s credentials are present.

(fix): Fix empty object and empty map serialization to produce {} instead of []. This applies to top-level objects, nested objects, and empty map-typed properties.

(fix): Emit the native PHP enum case (instead of its backing string value) when an enum is passed to a discriminated-union factory argument in dynamic snippets, matching the generated factory signature.

(fix): Use the backing value type (value-of<Enum>) for enum map keys in PHPDoc so PHPStan can resolve the type. PHP array keys must be int|string, so the native enum type produced an unresolvable type.

(fix): Fix the generated OAuth token provider to forward required non-literal token request properties (custom scopes and other required body properties such as an entity id) to the token endpoint. Previously these properties were silently dropped, so the generated typed token request was missing required keys and failed PHPStan. They are now collected as client constructor parameters and threaded through to the token request.

(fix): Fix dynamic snippets to emit required variable-typed path parameters. A path parameter typed by a Fern variable is a required argument on the generated SDK method but is not provided as an explicit snippet value, so the snippet previously omitted it and failed to type-check. The generator now synthesizes a placeholder value for these parameters so the required argument is emitted.

(fix): Serialize boolean path parameters as “true”/“false” instead of relying on PHP’s string coercion (which renders them as “1”/""), producing valid URLs.

(fix): Skip bytes request body endpoints when generating wire tests, matching the WireMock stub generator which omits them. Previously the generated test called an endpoint with no matching stub and failed.

(fix): Fix the generated OAuth and inferred-auth token providers to construct the typed token request object when the token endpoint uses a referenced (non-inlined) request body. Previously the provider passed an associative array to the token endpoint method, which expects the typed request, causing PHPStan failures.

(fix): Fix dynamic snippet argument ordering for discriminated union factory methods with optional base properties. Required base fields now come before the variant value, and optional base fields come after, matching the PHP Method AST’s automatic parameter reordering.

(fix): Fix dynamic snippet generation: filter out unsupported bytes body arguments that produced syntax errors, and reorder IR-level path parameters (which have defaults) after required body parameters to match the SDK method signatures.

(fix): Fix union serialization for enum variants: use ->value for serialization and ::from() for deserialization instead of ->jsonSerialize() / ::jsonDeserialize().

(fix): Fix PHPStan error for literal boolean headers by using strict null comparison (!== null) instead of loose comparison (!= null).

(fix): Fix multiple PHP generator bugs: add missing HEAD enum case, fix fully-qualified exception class references, use preserveEnums for union return types, fix required parameter ordering after optional parameters, prevent toJson on literal types, cast boolean header values to strings, and fix basic-auth null checks when env vars are set.

(fix): Generated discriminated unions no longer emit a fromJson() override. The base JsonSerializableType::fromJson now uses late static binding (static::jsonDeserialize) so subclasses’ typed jsonDeserialize overrides dispatch correctly. This eliminates ~50 lines of duplicated code per union and resolves a PHPStan strict failure where the union override’s $decodedJson was narrowed to array<array-key, mixed> instead of array<string, mixed>.