fix(jsonapi): sparse fieldsets on included resources - #8584
Merged
soyuka merged 5 commits intoSep 28, 2026
Merged
Conversation
Two defects compounded to hide the "included" member: JsonApiProvider matched fields[TYPE] against include's relation NAMES, but per the JSON:API spec fields[TYPE] names a resource TYPE (author vs people) — a spec-correct request never matched and "included" was never set. Resolve each included relation's target resource type via existing property/resource metadata factories and accept it as an additional, non-replacing match alongside the legacy relation-name comparison. Separately, SparseFieldsetParameterProvider scoped a fields[TYPE] key naming a related resource against the HOST operation's allowed properties instead of that related resource's own, so nothing matched even when reached directly.
SparseFieldsetParameterProvider (the fix for the reported Laravel bug, api-platform#7267) is registered only by Laravel, so the existing Symfony functional test could never reach it. Add a Laravel test that fails without the provider's host-vs-related property fix and passes with it. Also stop defaulting JsonApiProvider's new metadata-factory arguments to null: the bundle always wires them, so the nullability only existed to keep the bare-constructed unit test compiling. Update that test to build real collaborators instead.
The included-resource fieldset only applied when filters were declared through the deprecated #[ApiFilter] attribute. Register the sparse fieldset parameter provider and filter as services, and resolve a fields[TYPE] key to the host property name the serializer whitelists.
SparseFieldset must be registered in the api_platform.filter locator: that registration is what makes getFilterInstance() return an instance, and with it the parameter's schema, its OpenAPI parameter, its provider and its properties. But OpenApiFactory reads the same locator and calls getDescription() on every entry, so a filter implementing only the newer capability interfaces broke the whole document. getDescription() is deprecated since 4.2 and goes away in 5.0, so an entry that is not a FilterInterface has no description to contribute.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #7267.
fields[TYPE]=...&include=relationNamesilently dropped theincludedmember from JSON:API responses. Two compounding defects:JsonApiProvider::transformFieldsetsParameters()decided whether to emitincludedby comparing afields[...]key against theincludelist's relation names. Per the JSON:API spec,fields[TYPE]names a resource type (fields[people]), whileincludenames a relationship (include=author) — different namespaces. A spec-correct request (fields[TargetType]) never matched, soincludedwas never set. Fixed by resolving each included relation's target resource type (via the property/resource metadata factories already injected elsewhere in the JsonApi component) and accepting a type-name match in addition to the existing relation-name match — the legacy behaviour is preserved, not replaced, andRelatedResourcesInclusionTest(which pins it) still passes unmodified.SparseFieldsetParameterProvider::provide()(the opt-in,QueryParameter-based sparse-fieldset filter used e.g. by Laravel) scoped afields[TYPE]key naming a related resource against the host operation's allowed properties, so nothing ever matched for a related type. Now resolves the named type to its own resource class and validates fields against that resource's own readable properties.Test plan
SparseFieldsetParameterProviderIncludeTest::testIncludedResourceKeepsItsOwnRequestedFields— red before (Failed asserting that an array has the key 'included'), green after.RelatedResourcesInclusionTest(guards the legacy relation-name matching) — full file, 15 tests / 76 assertions, green.JsonApiProviderTest(unit) — 5 tests, green (pre-existing PHPUnit notice unrelated to this change).PHP_CS_FIXER_IGNORE_ENV=1 vendor/bin/php-cs-fixer fix— clean.vendor/bin/phpstan analyseon changed files — no errors.Broader regression scope left to CI.