Skip to content

Document three undocumented 5.0 behaviors (state, serialization, errors) - #2336

Merged
soyuka merged 1 commit into
api-platform:mainfrom
soyuka:docs/5.0-state-sti-errors
Sep 13, 2026
Merged

Document three undocumented 5.0 behaviors (state, serialization, errors)#2336
soyuka merged 1 commit into
api-platform:mainfrom
soyuka:docs/5.0-state-sti-errors

Conversation

@soyuka

@soyuka soyuka commented Sep 12, 2026

Copy link
Copy Markdown
Member

Summary

Three undocumented API Platform 5.0-only behaviour changes, verified against api-platform/core at upstream/main:

  • core/state-providers.md — a ParameterProviderInterface on a uriVariables Link can now replace the URI variable value used to fetch the resource (core #8491, commit fce2bdfe6). Documents the default transform-and-replace behaviour and the PreservesUriVariableInterface / write_uri_variable opt-out used by ReadLinkParameterProvider.
  • core/serialization.md — for Doctrine JOINED/SINGLE_TABLE inheritance, a serializer group declared only on a discriminator subclass is now taken into account when deciding whether a relation is embedded (core #8283, commit a8af8e1b9). This is a behaviour change for existing APIs: relations that used to serialize as an IRI may now be embedded. Documents the rule and the readableLink/writableLink: false opt-out to keep the old behaviour.
  • core/errors.md — the default exception_to_status mapping was undocumented and the shipped Symfony config sample had drifted from the source (wrong InvalidArgumentException namespace, a nonexistent ValidationExceptionInterface class). Reconciled against Configuration::addExceptionToStatusSection(): SerializerExceptionInterface => 400, InvalidArgumentException => 400, OptimisticLockException => 409, and the new UniqueConstraintViolationException => 422 (core #8478).

Each claim was checked directly against the shipped PHP source (see commit messages for file:line references), not copied from the audit prose.

Not fixed (out of scope, flagged for follow-up)

  • core/errors.md's Laravel exception_to_status example still lists a mismatched default set (ExceptionInterface, InvalidArgumentException, phantom ValidationExceptionInterface) that doesn't match Laravel's actual shipped default (Illuminate\Auth\AuthenticationException => 401, Illuminate\Auth\Access\AuthorizationException => 403, see src/Laravel/config/api-platform.php:116-119). Left untouched — unrelated to the Doctrine/UniqueConstraintViolationException scope of this PR and would need its own verification pass.
  • G7 (serialization.md) may overlap with open PR feat: support polymorphism #2278 ("support polymorphism") — worth checking before merge.

Test plan

  • npx prettier@3.9.5 --check "**/*.md" --prose-wrap always — only pre-existing failures in core/doctrine-filters.md and core/filters.md remain (untouched by this PR).

@soyuka
soyuka force-pushed the docs/5.0-state-sti-errors branch from 67444f7 to fd7aca5 Compare September 13, 2026 07:41
@soyuka
soyuka merged commit 8a5d31d into api-platform:main Sep 13, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant