---
name: api-platform-dto-resources
description: Map entities to API DTOs in API Platform (v5, 4.4, 4.3) with the Symfony Object Mapper (#[Map], stateOptions) for decoupled input/output contracts
capabilities: [read, search, edit, shell]
tags: [api-platform]
# projected by `bun run build` — do not edit by hand
allowed-tools:
  - Read
  - Glob
  - Grep
  - Write
  - Edit
  - Bash
---

# Api Platform Dto Resources (Symfony)

## Use when
- The `#[ApiResource]` class must be the API contract, decoupled from the Doctrine entity.
- Entity and API fields differ in name or format (rename, formatted price, computed value).
- Create, update, or list operations need their own input or output shape.
- Migrating code that relied on `DataTransformerInterface`, which no longer exists.

## Default workflow
1. Require `symfony/object-mapper` and set `stateOptions: new Options(entityClass: ...)` on the DTO resource.
2. Bind the DTO and the entity with `#[Map(source: ...)]` and `#[Map(target: ...)]`, and use `#[Map(transform: ...)]` for computed fields.
3. For distinct shapes, create input and output classes and wire them with `input:` and `output:` on each operation.
4. When mapping needs real logic, write a custom `ProcessorInterface` that calls `ObjectMapperInterface::map()`.
5. Test each operation: payload in, response shape out.

## Guardrails
- The automatic Object Mapper provider and processor only apply when `stateOptions` has an `entityClass` and both the DTO and the entity carry `#[Map]`.
- `DataTransformerInterface` is gone: use Object Mapper or a provider and processor.
- No Object Mapper on 3.4 or on Symfony 6.4 LTS (it needs Symfony 7.3+): map manually in a `ProviderInterface` and a `ProcessorInterface`.
- `ObjectMapperProcessor` is removed in 5.0: the automatic path uses `ObjectMapperInputProcessor` and `ObjectMapperOutputProcessor` (4.3+).
- Never return the entity itself from a DTO resource: only mapped fields reach the client.

## Progressive disclosure
- Use this file for execution posture and risk controls.
- Open references when deep implementation details are needed.

## Output contract
- The resource, input, and output classes with their `#[Map]` bindings.
- The mapping path chosen (Object Mapper or custom processor) and why.
- Tests showing the request and response shape of each operation.

## References
- `reference.md`