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.

Un PATCH par transition : API Platform filtre, le processor décide sous verrou API Platform, avant le processor 1. lire la commande (provider Doctrine) 2. vérifier les droits ( security ) 3. valider CancelOrderInput 404 commande inconnue ou filtrée 403 ni propriétaire, ni support 422 motif absent, vide ou trop long WorkflowTransitionProcessor , une transaction 4. BEGIN, lock() FOR UPDATE, refresh() une transition concurrente attend ici 5. can('cancel') ? non 409 ROLLBACK, raisons du workflow 6. motif copié, apply() , flush() les listeners écrivent l'outbox PATCH /orders/{id}/cancel {"reason": "Commande passée deux fois."} oui 7. COMMIT 200 OrderResource , @id /orders/{id}

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 : object est l'entité lue. Le voter ORDER_CANCEL accepte le client propriétaire et le support : il juge l'identité, le workflow juge l'état.
  • allow_extra_attributes: false : un status envoyé au POST est refusé (400) au lieu d'être ignoré.
  • item_uri_template : API Platform calcule l'@id depuis l'opération en cours, ici /orders/{id}/cancel. itemUriTemplate n'existe que sur Post et GetCollection : ce contexte désigne donc le Get par 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: false refuse un champ inconnu.
  • Une opération PATCH /<ressource>/{id}/<transition> par transition, avec sa règle security.
  • map: false sur les transitions, et la transition nommée dans extraProperties.
  • Un verrou sur la seule ligne (lock()), puis refresh(), 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_template vers le Get de 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.