Le problème
Dans notre boutique en ligne, chaque commande du service
order suit
une machine à états Symfony nommée order. Elle naît draft, puis passe
placed, paid et
shipped. Avant l'expédition, elle peut être
annulée (cancelled), avec un motif obligatoire.
Le plus court est d'exposer le statut comme un champ
ordinaire : PATCH /orders/{id} avec
{"status": "shipped"}. Le client écrit alors
l'état lui-même.
Tous les sauts deviennent possibles. Une
contrainte Choice vérifie que la valeur existe,
pas le chemin. Une commande placed passe
shipped sans paiement.
Le workflow est contourné. Écrire la
propriété n'appelle pas apply() : ni
guard, ni listener. L'événement que le listener
completed dépose dans l'outbox ne part jamais.
Deux requêtes, deux décisions. L'entrepôt
expédie pendant que le support annule. Les deux requêtes
lisent paid et écrivent chacune leur
statut : les deux effets ont lieu.
Des données hors contexte. Le motif d'annulation devient un champ libre, écrit à tout moment, vide ou non.
Des relations écrites par IRI. Le front
manipule des UUID, mais doit envoyer
/customers/{id} pour désigner le client. Le
contrat d'écriture dépend des routes.
Les options
Le champ status en écriture, contrôlé par un
validateur
- Ce qu'elle règle : aucune route de plus. Un validateur compare l'ancien et le nouveau statut.
- Ce qu'elle coûte : ce validateur recopie le workflow, sans ses guards ni ses listeners, et ne voit pas la requête concurrente.
Une opération générique de transition
POST /orders/{id}/transitions, avec
{"transition": "ship"} dans le corps.
- Ce qu'elle règle : une seule route, et c'est le workflow qui applique la transition.
- Ce qu'elle coûte : un même schéma d'entrée pour toutes les transitions. Le motif devient un champ optionnel, et les droits se décident dans le code, invisibles dans OpenAPI.
Une opération par transition
PATCH /orders/{id}/place, /pay,
/ship et /cancel.
- Ce qu'elle règle : chaque transition a son entrée, sa règle d'accès et sa documentation. Un processor commun applique le workflow.
- Ce qu'elle coûte : une opération à déclarer par transition, et trois réglages d'API Platform à connaître.
Notre recommandation
Le statut est en lecture seule. Chaque transition est une
opération
PATCH /orders/{id}/<transition>,
traitée par un processor commun, dans une seule
transaction.
API Platform fait d'abord son travail ordinaire : il
lit la commande (404), évalue la règle
security (403) et valide la charge utile (422).
Un motif vide n'atteint jamais le workflow. Le processor
verrouille ensuite la ligne et la relit, demande
can() au workflow, puis appelle
apply() et flush() avant de
commiter.
Les deux codes d'erreur diffèrent. Un 422 signale une requête invalide en elle-même, quel que soit l'état. Un 409 signale un conflit avec l'état courant : la même annulation aurait réussi avant l'expédition.
Les relations s'écrivent par UUID : une contrainte vérifie leur existence pendant la validation, puis ObjectMapper les convertit en entités. La ressource devient plate : c'est le cas où notre article sur ObjectMapper recommande ce composant.
PATCH, et la lecture d'API Platform
POST avec status: 200 conviendrait aussi :
c'est la forme de
notre article sur l'outbox. Mais cet exemple désactive la lecture (read: false) et charge la commande dans le processor.
Nous gardons la lecture d'API Platform. Une commande
inconnue répond 404, security reçoit l'entité,
et
les extensions de requête Doctrine
filtrent ce que l'utilisateur peut atteindre. Le processor
n'a plus qu'à verrouiller et relire.
Les compromis assumés
Une opération par transition. La ressource s'allonge, OpenAPI aussi. C'est ce qui documente qui peut faire quoi.
Une attente sous verrou. Une seconde transition sur la même commande attend la fin de la première. Nous gardons la transaction courte : aucun appel HTTP dans les listeners, l'outbox s'en charge.
Un verrou plutôt qu'une version. Un verrou
optimiste (colonne version) éviterait
l'attente, et API Platform répond 409 par défaut sur
OptimisticLockException. Mais le client doit
alors réessayer.
Des UUID au lieu d'IRI.
"customerId": "0199..." ne se suit pas comme un
@id. Le schéma OpenAPI annonce
format: uuid sans nommer la ressource
visée : nous la nommons dans la description du champ.
Le signal qui doit faire réexaminer ce choix : une transition qui appelle un service externe, comme un prestataire de paiement. Elle passe alors en asynchrone, appliquée par un handler Messenger.
Mise en œuvre
Les exemples ciblent Symfony 7.4 et 8.1, API Platform 4.4, Doctrine ORM 3.7 et PostgreSQL. La 5.0.7 a le même code sur ces points. Entités et ressources suivent notre article sur les ressources DTO, sauf les relations, écrites ici par UUID.
1. Les places et les transitions
Les places sont les constantes d'une
final class OrderStatus (DRAFT,
PLACED, PAID,
SHIPPED, CANCELLED), les
transitions celles d'une
final class OrderTransition :
// src/Workflow/OrderTransition.php
namespace App\Workflow;
// Les mêmes noms que config/packages/workflow.yaml.
final class OrderTransition
{
public const PLACE = 'place';
public const PAY = 'pay';
public const SHIP = 'ship';
public const CANCEL = 'cancel';
}
# config/packages/workflow.yaml (service order)
framework:
workflows:
order:
type: state_machine
marking_store:
type: method
property: status
supports:
- App\Entity\Order
initial_marking: draft
places: [draft, placed, paid, shipped, cancelled]
transitions:
place: { from: draft, to: placed }
pay: { from: placed, to: paid }
ship: { from: paid, to: shipped }
cancel: { from: [placed, paid], to: cancelled }
Order porte getStatus() et
setStatus() pour le marking store,
setCancellationReason(),
setCarrier() et
setTrackingNumber(). Aucune entrée ne porte
status.
2. Une opération par transition
// src/ApiResource/OrderResource.php
namespace App\ApiResource;
use ApiPlatform\Doctrine\Orm\State\Options;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Patch;
use ApiPlatform\Metadata\Post;
use App\ApiResource\Input\CancelOrderInput;
use App\ApiResource\Input\CreateOrderInput;
use App\ApiResource\Input\ShipOrderInput;
use App\Entity\Customer;
use App\Entity\Order;
use App\State\WorkflowTransitionProcessor;
use App\Workflow\OrderTransition;
use Symfony\Component\ObjectMapper\Attribute\Map;
use Symfony\Component\Uid\Uuid;
#[ApiResource(
shortName: 'Order',
operations: [
new GetCollection(),
new Get(name: 'order_get'),
new Post(input: CreateOrderInput::class, denormalizationContext: ['allow_extra_attributes' => false]),
// place et pay suivent ce modèle, avec input: false.
new Patch(
uriTemplate: '/orders/{id}/ship',
security: "is_granted('ROLE_WAREHOUSE')",
input: ShipOrderInput::class,
map: false,
processor: WorkflowTransitionProcessor::class,
normalizationContext: ['item_uri_template' => 'order_get'],
extraProperties: ['transition' => OrderTransition::SHIP],
),
new Patch(
uriTemplate: '/orders/{id}/cancel',
security: "is_granted('ORDER_CANCEL', object)",
input: CancelOrderInput::class,
map: false,
processor: WorkflowTransitionProcessor::class,
normalizationContext: ['item_uri_template' => 'order_get'],
extraProperties: ['transition' => OrderTransition::CANCEL],
),
],
stateOptions: new Options(entityClass: Order::class),
collectDenormalizationErrors: true,
)]
#[Map(source: Order::class)]
final readonly class OrderResource
{
public function __construct(
public Uuid $id,
public string $reference,
// Lu depuis l'entité : aucune entrée ne l'écrit.
public string $status,
// Un UUID, comme à l'écriture.
#[Map(source: 'customer', transform: [self::class, 'idOf'])]
public Uuid $customerId,
public ?string $cancellationReason,
public ?string $carrier,
public ?string $trackingNumber,
) {
}
public static function idOf(Customer $customer): Uuid
{
return $customer->getId();
}
}
-
map: false: le provider Doctrine remet l'entité elle-même au processor. Avec le mapping actif, il recevrait la ressource. -
security:objectest l'entité lue. Le voterORDER_CANCELaccepte le client propriétaire et le support : il juge l'identité, le workflow juge l'état. -
allow_extra_attributes: false: unstatusenvoyé au POST est refusé (400) au lieu d'être ignoré. -
item_uri_template: API Platform calcule l'@iddepuis l'opération en cours, ici/orders/{id}/cancel.itemUriTemplaten'existe que surPostetGetCollection: ce contexte désigne donc leGetpar son nom.
3. Le processor commun
// src/State/WorkflowTransitionProcessor.php
namespace App\State;
use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\ProcessorInterface;
use Doctrine\DBAL\LockMode;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\HttpKernel\Exception\ConflictHttpException;
use Symfony\Component\ObjectMapper\ObjectMapperInterface;
use Symfony\Component\Workflow\Registry;
use Symfony\Component\Workflow\TransitionBlocker;
/** @implements ProcessorInterface<object, object> */
final readonly class WorkflowTransitionProcessor implements ProcessorInterface
{
public function __construct(
private EntityManagerInterface $em,
private Registry $workflows,
private ObjectMapperInterface $objectMapper,
) {
}
public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): object
{
$transition = $operation->getExtraProperties()['transition'];
// Avec une entrée, $data est le DTO validé, et API Platform garde l'entité lue dans read_data.
$hasInput = null !== ($operation->getInput()['class'] ?? null);
$entity = $hasInput ? $context['read_data'] : $data;
$workflow = $this->workflows->get($entity);
$connection = $this->em->getConnection();
$connection->beginTransaction();
try {
// SELECT 1 FROM orders t0 WHERE t0.id = ? FOR UPDATE : une transition concurrente attend ici.
$this->em->lock($entity, LockMode::PESSIMISTIC_WRITE);
// Relue sous le verrou : l'état est celui qu'a commité la requête précédente.
$this->em->refresh($entity);
if (!$workflow->can($entity, $transition)) {
$reasons = array_map(
static fn (TransitionBlocker $blocker): string => $blocker->getMessage(),
iterator_to_array($workflow->buildTransitionBlockerList($entity, $transition)),
);
throw new ConflictHttpException(trim(\sprintf('The "%s" transition cannot be applied. %s', $transition, implode(' ', $reasons))));
}
if ($hasInput) {
// Le motif d'annulation, ou le transporteur et le numéro de suivi.
$this->objectMapper->map($data, $entity);
}
// Les listeners du workflow, dont l'outbox, écrivent dans cette transaction.
$workflow->apply($entity, $transition);
$this->em->flush();
$connection->commit();
} catch (ConflictHttpException $e) {
// Rien n'a été écrit : l'EntityManager reste utilisable.
$connection->rollBack();
throw $e;
} catch (\Throwable $e) {
// Erreur inattendue : annuler, puis fermer comme le recommande Doctrine.
if ($connection->isTransactionActive()) {
$connection->rollBack();
}
$this->em->close();
throw $e;
}
return $this->objectMapper->map($entity, $operation->getClass());
}
}
Verrouiller la seule ligne.
lock() exécute
SELECT 1 ... FOR UPDATE sur la table de
l'entité, puis refresh() la relit.
find() ou refresh() avec un mode
de verrou ajoutent FOR UPDATE à toute la
requête de chargement. PostgreSQL verrouille aussi les
lignes des jointures EAGER, ou refuse la
requête sur un LEFT JOIN.
Le pourquoi du verrou est dans
notre article sur l'outbox : l'annulation qui attendait relit
shipped et reçoit son 409.
Copier l'entrée après can().
Sur un 409, l'entité en mémoire reste celle de la base. Si
une guard doit lire la charge utile, copiez-la avant
can() et relisez l'entité dans la branche du
409.
Un 409 explicite. Le message reprend les
raisons du workflow, et API Platform le renvoie dans
detail pour un 4xx. apply() lève
NotEnabledTransitionException si la transition
n'est pas permise : déclarée à 409 dans
exceptionToStatus, elle couvre les transitions
appliquées ailleurs.
Pas de wrapInTransaction().
Doctrine le documente : sur une exception, il annule la
transaction et ferme l'EntityManager. Après un 409, tout
code qui l'utilise encore lèverait
EntityManagerClosed, alors que rien n'a été
écrit. L'article sur l'outbox s'en sert sans dommage :
rien n'y réutilise ensuite l'EntityManager, ce qu'un
processor commun ne peut garantir.
4. Les entrées : un 422 avant le workflow
// src/ApiResource/Input/CancelOrderInput.php
namespace App\ApiResource\Input;
use App\Entity\Order;
use Symfony\Component\ObjectMapper\Attribute\Map;
use Symfony\Component\Validator\Constraints as Assert;
#[Map(target: Order::class)]
final readonly class CancelOrderInput
{
public function __construct(
#[Assert\NotBlank(normalizer: 'trim')]
#[Assert\Length(max: 500)]
#[Map(target: 'cancellationReason')]
public string $reason,
) {
}
}
PATCH /orders/0199b1a0-7c3e-7d2a-9f10-2b6c1d4e5f60/cancel HTTP/1.1
Content-Type: application/merge-patch+json
{"reason": "Commande passée deux fois."}
| Situation | Réponse | Étape |
|---|---|---|
| Commande inconnue, ou filtrée par une extension | 404 | lecture |
| Ni le client propriétaire, ni le support | 403 | security |
| Motif absent, vide ou trop long | 422 | désérialisation, puis validation |
Commande en draft, expédiée ou déjà
annulée
|
409 | can() |
Commande placed ou paid
|
200 | COMMIT |
ShipOrderInput suit le même modèle, avec deux
champs obligatoires :
// src/ApiResource/Input/ShipOrderInput.php
namespace App\ApiResource\Input;
use App\Entity\Order;
use Symfony\Component\ObjectMapper\Attribute\Map;
use Symfony\Component\Validator\Constraints as Assert;
// Les noms des propriétés de Order : aucun #[Map] par champ.
#[Map(target: Order::class)]
final readonly class ShipOrderInput
{
public function __construct(
#[Assert\NotBlank(normalizer: 'trim')]
public string $carrier,
#[Assert\NotBlank(normalizer: 'trim')]
public string $trackingNumber,
) {
}
}
Une transition sans entrée (input: false)
n'attend ni corps ni Content-Type. Avec une
entrée, elle accepte les formats des PATCH,
application/merge-patch+json par défaut, et
répond 415 aux autres.
5. Les relations par UUID
// src/ApiResource/Input/CreateOrderInput.php
namespace App\ApiResource\Input;
use App\Entity\Customer;
use App\Entity\Order;
use App\Mapper\UuidToCustomer;
use App\Validator\EntityExists;
use Symfony\Component\ObjectMapper\Attribute\Map;
use Symfony\Component\Uid\Uuid;
use Symfony\Component\Validator\Constraints as Assert;
#[Map(target: Order::class)]
final readonly class CreateOrderInput
{
public function __construct(
#[Assert\NotBlank, Assert\Length(max: 32)]
public string $reference,
// Un UUID, pas une IRI : vérifié à la validation, converti au mapping.
#[EntityExists(entity: Customer::class)]
#[Map(target: 'customer', transform: UuidToCustomer::class)]
public Uuid $customerId,
) {
}
}
EntityExists suit la documentation de
Symfony : une option
entity (#[HasNamedArguments]) et
un message. Son validateur reçoit
l'EntityManager :
// src/Validator/EntityExistsValidator.php (extrait)
public function validate(mixed $value, Constraint $constraint): void
{
// Absent ou null : NotNull décide si le champ est obligatoire.
if ($value instanceof Uuid && null === $this->em->find($constraint->entity, $value)) {
$this->context->buildViolation($constraint->message)
->setParameter('{{ uuid }}', $value->toRfc4122())
->addViolation();
}
}
// src/Mapper/UuidToCustomer.php
namespace App\Mapper;
use App\Entity\Customer;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\ObjectMapper\TransformCallableInterface;
/** @implements TransformCallableInterface<object, object> */
final readonly class UuidToCustomer implements TransformCallableInterface
{
public function __construct(
private EntityManagerInterface $em,
) {
}
public function __invoke(mixed $value, object $source, ?object $target): ?Customer
{
// Déjà chargé par le validateur : find() le relit dans l'identity map, sans requête.
return null === $value ? null : $this->em->find(Customer::class, $value);
}
}
Un UUID inconnu donne un 422 sur le chemin
customerId, avec les autres violations, avant
tout mapping.
Et dans un PATCH ? Un champ absent reste
non initialisé, pas null (voir
notre article sur les ressources DTO). ObjectMapper ne saute une telle propriété portant un
#[Map] que depuis symfony/object-mapper 7.4.14
et 8.1.1 (27 juin 2026). Avant, il levait une erreur.
Un null sur une relation obligatoire donne un
422 : collectDenormalizationErrors fait de
l'erreur de type une violation. Une liste d'UUID remplace la
collection par l'adder et le remover, et
[] délie tout. Une relation nullable marquée
#[Map(if: new IsNotNull())] (Symfony 8.1)
traite null comme un champ absent.
Checklist
-
Aucune entrée ne porte le statut, et
allow_extra_attributes: falserefuse un champ inconnu. -
Une opération
PATCH /<ressource>/{id}/<transition>par transition, avec sa règlesecurity. -
map: falsesur les transitions, et la transition nommée dansextraProperties. -
Un verrou sur la seule ligne (
lock()), puisrefresh(), dans une transaction. - Un 409 avec les raisons du workflow, sans fermer l'EntityManager.
- Une entrée validée (422) pour toute transition qui demande des données.
-
item_uri_templatevers leGetde la ressource. - Des relations écrites par UUID : contrainte d'existence, puis transformation.
- Des tests qui relisent l'état après un 409 et un 422.
Sources
Versions relevées le 15 novembre 2026 : Symfony 8.1.11 et 7.4.23, API Platform 4.4.8 et 5.0.7, Doctrine ORM 3.7.7.
-
Symfony,
Workflow,
WorkflowInterface
et
NotEnabledTransitionException :
can(),apply(),buildTransitionBlockerList(). -
Symfony,
ObjectMapper
et
TransformCallableInterface :
transform,if,IsNotNull. -
Symfony, ObjectMapper :
le correctif qui saute les propriétés illisibles
portant un
#[Map], publié dans 7.4.14 et 8.1.1. - Symfony, contrainte personnalisée.
-
API Platform,
Operations,
State Processors,
DTO
(
read_data), Security et Errors Handling (exceptionToStatus). -
API Platform, code de la 4.4.8 :
ObjectMapperMetadataCollectionFactory
(
map), ContentNegotiationProvider (415), IriConverter (item_uri_template) et Configuration (statuts par défaut). -
Doctrine ORM,
Transactions and Concurrency,
EntityManager
et
BasicEntityPersister :
wrapInTransaction(),lock(), jointuresEAGER. - PostgreSQL, clause de verrouillage : lignes verrouillées dans une jointure ; initsplan.c : jointure externe refusée.
- IETF, RFC 9110 : 409 Conflict et 422 Unprocessable Content.
- Lychen, pull requests 251, 253 et 255 : une mise en œuvre open source de ce que décrit cet article, dans un monorepo moon.