feat(php): make idempotency key generation IR-driven

[devin-ai-integration]

Description

Makes the PHP SDK generator's auto-generated idempotency key IR-driven, mirroring the TypeScript reference (#17007). Instead of the previous per-generator config flag + hardcoded POST/PUT, the generator now reads ir.sdkConfig.idempotencyKeyGeneration (optional block with headerName and methods). Field present = enabled; absent = disabled.

The IR v67 upgrade this depends on (sdkConfig.idempotencyKeyGeneration only exists in IR v67) landed in #17026, now merged to main. This branch is rebased onto main, so the diff below is only the idempotency change.

Changes Made

• HttpEndpointGenerator: attach the IR-configured header (default Idempotency-Key) with a freshly generated UUIDv4 on the IR-configured eligible methods (default POST/PUT). Caller-supplied value wins; method gating and header name come from the IR (no hardcoded POST/PUT).
• New IdempotencyKey core helper (random_bytes(16) RFC 4122 v4 UUID). Shipped only when sdkConfig.idempotencyKeyGeneration != null (SdkGeneratorContext.getCoreAsIsFiles), so flag-OFF output is byte-identical to main.
• Removed the per-generator config plumbing; no double-support of old + new.
• packages/commons/api-workspace-commons/checkVersionExists.ts: added getGeneratorConfigObject() (falls back to generatorInvocation.config when raw.config is absent) used by getIdempotencyKeyGenerationFromGeneratorConfig() — the shared seed-harness fix, verbatim from the TS branch. +4 unit tests.
• Seed fixture idempotency-headers split into no-custom-config (disabled) and auto-generate-idempotency-key (enabled) variants.

Testing

• Unit tests added/updated — @fern-api/api-workspace-commons suite green (checkVersionExists.test.ts).
• Manual testing completed — pnpm seed test --generator php-sdk --fixture idempotency-headers --local --skip-scripts: 2/2 pass.
  • auto-generate-idempotency-key variant, PaymentClient::create (POST): $headers['Idempotency-Key'] = $options['headers']['Idempotency-Key'] ?? IdempotencyKey::generate(); (caller-wins + UUID fallback).
  • PaymentClient::delete (DELETE): no injection.
  • no-custom-config variant: no IdempotencyKey helper and no header injection (byte-identical to disabled/main behavior).

Link to Devin session: https://app.devin.ai/sessions/ee9a7e8220314b9a832a30a1c0bbfaa6
Requested by: @cadesark

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[nitpickybot]

AI Review Summary

The PR ports auto-generate idempotency key to the PHP SDK, gated behind a config flag. The core mechanism is sound, but the header-bag reference wiring has a bug that will drop caller-supplied header parameters when both a header parameter block and the idempotency block exist.

• 🔴 1 critical issue(s)
• 🟡 1 warning(s)

[nitpickybot]

🔴 critical

When hasExistingHeaderBag is true, this block writes into $headers (HEADER_BAG_NAME), but the existing headerParameterCodeBlock populates its own variable (headerParameterBagReference). If those two references differ, the idempotency key lands in a different array than the one holding the caller's header params — and since headerBagReference below prefers the idempotency block's $headers, the header-parameter bag gets dropped from the request entirely.

Either reuse headerParameterCodeBlock.headerParameterBagReference as the target when it exists, or verify they're always the same variable. Otherwise declared header params silently vanish on POST/PUT when the flag is on.

[devin-ai-integration]

Addressed in 2a18937. The idempotency block now reuses `headerParameterCodeBlock.headerParameterBagReference` when it exists (both blocks were already writing to the same $headers var, but this makes it explicit and robust) and only declares a fresh bag when there is no existing one — so declared header params can never be dropped.

[nitpickybot]

🟡 warning

This reads $options['headers']['Idempotency-Key'] with an exact-case key, but the declaresIdempotencyKeyHeader check above does a case-insensitive match on the wire name. A header declared as e.g. idempotency-key would pass the check but the caller-wins lookup here uses the hardcoded Idempotency-Key casing, so it won't find a value under the actual declared name. Use the endpoint's declared wire value for the lookup key to stay consistent.

[devin-ai-integration]

Addressed in 2a18937. The lookup now uses the endpoint's declared wire value (getWireValue(declaredIdempotencyHeader.name)) for both the emitted header key and the $options['headers'][...] caller-wins lookup, so casing stays consistent with the case-insensitive match. The literal Idempotency-Key is only used for the standalone (non-declared) plain POST/PUT path.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 1 additional finding.

[github-actions]

SDK Generation Benchmark Results

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

Full benchmark table (click to expand)

Generator	Spec	main (generator)	main (E2E)	PR (generator)	Delta
php-sdk	square	61s (n=5)	85s (n=5)	48s	-13s (-21.3%)

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-07-13T05:08:13Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-07-13 21:36 UTC

[github-actions]

Docs Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-07-10T05:18:08Z).

Fixture	main	PR	Delta
docs	241.5s (n=5)	251.1s (35 versions)	+9.6s (+4.0%)

Docs generation runs fern generate --docs --preview end-to-end against the benchmark fixture with 35 API versions (each version: markdown processing + OpenAPI-to-IR + FDR upload).
Delta is computed against the nightly baseline on main.
Baseline from nightly run(s) on main (latest: 2026-07-10T05:18:08Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-07-11 00:11 UTC

[devin-ai-integration]

Devin is archived and cannot be woken up. Please unarchive Devin if you want to continue using it.

[devin-ai-integration]

Devin is archived and cannot be woken up. Please unarchive Devin if you want to continue using it.

[devin-ai-integration]

Devin is archived and cannot be woken up. Please unarchive Devin if you want to continue using it.

[devin-ai-integration]

Devin is archived and cannot be woken up. Please unarchive Devin if you want to continue using it.