Skip to content

fix(state): map to the output class on mapped write operations - #8497

Open
dylan-rumble wants to merge 1 commit into
api-platform:5.0from
dylan-rumble:feat/object-mapper-output-dto-write-operation-support
Open

dylan-rumble wants to merge 1 commit into
api-platform:5.0from
dylan-rumble:feat/object-mapper-output-dto-write-operation-support

Conversation

@dylan-rumble

@dylan-rumble dylan-rumble commented Sep 2, 2026 •

Copy link
Copy Markdown
Contributor
Q A
Branch? 5.0
Tickets Refs #8849, follows #8848
License MIT
Doc PR none, the DTO chapter rewrite is listed in #8849

Rebased on 5.0 and reduced to what #8849 keeps from the original patch. The provider change (map to the resource class on unsafe methods) was merged on its own in #8848 and is no longer part of this PR.

Problem

On a resource mapped to an entity (stateOptions + #[Map]), ObjectMapperOutputProcessor maps the persisted entity to the resource class, also when the operation declares an output. A POST or PATCH answers with the resource shape while OpenAPI and Hydra document the output class.

What this PR changes

  1. ObjectMapperOutputProcessor maps to the output class (getOutput()['class'] ?? getClass()), as ObjectMapperProvider does on reads.
  2. Location and Content-Location are computed from the resource the operation acted on. When the output class is not the resource class, the processor also maps the entity to the resource class and stores it in the mapped_resource request attribute; HttpResponseHeadersTrait builds the IRI from it. No item template is needed for the headers.
  3. The status is about the resource too. HttpResponseStatusTrait reads the same attribute, so a PUT with allowCreate that creates keeps answering 201 when an output is declared.
  4. Data that already is an instance of the output class is not mapped again, for a custom processor that returns its own output object (third bullet of "What goes wrong today" in [RFC] An operation's output is its own resource #8849).

Operations without an output, or whose output is the resource class, are untouched: one mapping, same headers.

What was dropped

The original patch set item_uri_template implicitly from the operation's own uriTemplate on PATCH/PUT (SerializerContextBuilder and the headers trait). #8849 refuses that, and Post('/books/{id}/discount', output: DiscountResult::class) shows why. Both changes are gone, SerializerContextBuilder is not touched anymore.

Where this stands against #8849

RFC This PR
the provider maps to the resource on unsafe methods merged in #8848
ObjectMapperOutputProcessor maps to the output class done
Location and Content-Location are computed from the resource done, through the mapped_resource request attribute
a custom processor's own output is not mapped again done
no implicit item template done
itemUriTemplate on every HttpOperation, cascading from the resource not here, #8479
6.0 steps (collected classes, metadata-time errors, blank node rule, view @type, anonymous code paths) not here
input not touched

Points that need a decision or differ from the RFC:

  • Branch. The RFC lists this step for 5.1, this PR targets 5.0 and it changes the body of mapped writes that declare an output (to the documented one). Happy to retarget to main.
  • mapped_resource. The request attribute is how the resource reaches RespondProcessor, the RFC does not say how. It is only set when the output class is not the resource class. Another mechanism is fine with me.
  • A view on PATCH/PUT is not possible yet. Only Post has itemUriTemplate today, so until feat(metadata): add canonicalUriTemplate to resources and HTTP operations #8479 a PATCH/PUT output is always "another thing": own type, generated @id. The headers still point at the resource.
  • @type of a view. Post(output: ..., itemUriTemplate: ...) already gives the @type of the resource in JSON-LD. JSON:API gives the output short name as type (MappedOutputDto), that is left to the 6.0 step.
  • Blank nodes in HAL and JSON:API still get a genid (_links.self, data.id), also left to the 6.0 step and to the open question on JSON:API.
  • A custom processor that returns its own output is passed through without mapped_resource: headers and status then follow the existing logic, they are not computed from the resource.

Behavior to be aware of

  • One extra map() call per write when an output different from the resource class is declared, so #[Map] transforms run twice for that entity. The entity → resource mapping is the one every mapped write already performs today, no new mapping has to be declared.
  • A resource that cannot produce an IRI (the entity does not map its identifier to the resource): 5.0 answers 400 Unable to generate an IRI, this branch answers 201 with the output body and no Location/Content-Location.

Verified against 5.0

Same requests run against 5.0 and this branch, on POST, PATCH and PUT (update and create):

  • JSON-LD, HAL, JSON:API and JSON: status, Location and Content-Location are identical to 5.0, only the body changes to the output class.
  • Event listeners mode (USE_SYMFONY_LISTENERS=1): no regression. 5.0 sends no Location/Content-Location on mapped writes in that mode (with or without output), operations with an output now get them. Operations without an output are left as they are, that looks like a separate bug.

Not run: Laravel (same processor and RespondProcessor chain, but the workbench has no mapped write with an output) and MongoDB ODM. GraphQL mutations have their own processor chain and are not affected, as noted in #8849.

Tests

  • tests/Functional/MappedResourceOutputTest.php (new fixtures only):
    • POST with output + itemUriTemplate: body is the output DTO, @id, Location and Content-Location are the item IRI.
    • PATCH with output: body is the output DTO and is not given the IRI of the resource, Content-Location is the item IRI, unsent fields are preserved in the database.
    • PUT with output and allowCreate: 201 with the output DTO as body.
  • ObjectMapperOutputProcessorTest: maps to the declared output class, sets mapped_resource when the output differs, does not map data that already is the output class.

@dylan-rumble
dylan-rumble marked this pull request as ready for review September 2, 2026 13:49
@dylan-rumble
dylan-rumble marked this pull request as draft September 3, 2026 14:43
@dylan-rumble
dylan-rumble marked this pull request as ready for review September 3, 2026 14:45
@dylan-rumble
dylan-rumble changed the base branch from 4.3 to 4.4 September 21, 2026 12:57
@dylan-rumble
dylan-rumble force-pushed the feat/object-mapper-output-dto-write-operation-support branch from 3743ba6 to 1fb847a Compare September 21, 2026 13:01
@dylan-rumble
dylan-rumble force-pushed the feat/object-mapper-output-dto-write-operation-support branch from 1fb847a to f25a7ed Compare November 17, 2026 12:10
@dylan-rumble dylan-rumble changed the title fix(state): support output DTOs on write operations with ObjectMapper fix(state): map to the output class on mapped write operations Nov 17, 2026
@dylan-rumble
dylan-rumble changed the base branch from 4.4 to 5.0 November 17, 2026 12:10
With the Object Mapper, `ObjectMapperOutputProcessor` mapped the persisted
entity to the resource class even when the operation declares an `output`:
the body had the resource shape while OpenAPI and Hydra documented the
output class.

The processor now maps to the output class, as the provider does on reads.
`Location`, `Content-Location` and the status are about the resource the
operation acted on, they are computed from the entity mapped to the
resource class. Data that already is an instance of the output class is
not mapped again.

Refs api-platform#8849

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@dylan-rumble
dylan-rumble force-pushed the feat/object-mapper-output-dto-write-operation-support branch from f25a7ed to 7ba99e9 Compare November 17, 2026 12:16
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