Le problème

Le service order fait avancer chaque commande dans une machine à états Symfony nommée order. Ses places sont draft, placed, paid, shipped et cancelled, lues dans Order::$status.

Le back-office montre où en est une commande ; un agent qui appelle l'API cherche les étapes restantes. Recopier places et transitions dans chaque client crée une seconde source de vérité, qui diverge à la première transition ajoutée.

La solution

Symfony sait déjà dessiner un workflow : workflow:dump --dump-format=mermaid et le panneau Workflow du profiler s'appuient sur MermaidDumper. Sa méthode dump() accepte aussi un marquage : chaque place courante reçoit le style stroke-width:4px.

Nous servons ce texte par une opération API Platform, GET /orders/{id}/workflow. Le client le passe à mermaid.render() sans rien connaître du workflow. Les exemples ciblent API Platform 4.3 et Symfony 7.4 ou 8.1.

// src/ApiResource/WorkflowDiagram.php
namespace App\ApiResource;

final readonly class WorkflowDiagram
{
    public function __construct(
        public string $name,
        // Flowchart Mermaid, places courantes encadrées.
        public string $mermaid,
    ) {
    }
}
// src/State/WorkflowDiagramProvider.php
namespace App\State;

use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\ProviderInterface;
use App\ApiResource\WorkflowDiagram;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\Workflow\Debug\TraceableWorkflow;
use Symfony\Component\Workflow\Dumper\MermaidDumper;
use Symfony\Component\Workflow\Registry;
use Symfony\Component\Workflow\StateMachine;

final readonly class WorkflowDiagramProvider implements ProviderInterface
{
    public function __construct(
        #[Autowire(service: 'api_platform.doctrine.orm.state.item_provider')]
        private ProviderInterface $itemProvider,
        private Registry $workflows,
    ) {
    }

    public function provide(Operation $operation, array $uriVariables = [], array $context = []): ?WorkflowDiagram
    {
        // Même chargement que le Get de la ressource, extensions Doctrine comprises.
        $subject = $this->itemProvider->provide($operation, $uriVariables, $context);
        if (null === $subject) {
            return null; // API Platform répond 404.
        }

        $workflow = $this->workflows->get($subject);
        // En debug, le registre renvoie un TraceableWorkflow, qui masque le type réel.
        $inner = $workflow instanceof TraceableWorkflow ? $workflow->getInner() : $workflow;
        $dumper = new MermaidDumper($inner instanceof StateMachine
            ? MermaidDumper::TRANSITION_TYPE_STATEMACHINE
            : MermaidDumper::TRANSITION_TYPE_WORKFLOW);

        return new WorkflowDiagram(
            $workflow->getName(),
            $dumper->dump($workflow->getDefinition(), $workflow->getMarking($subject)),
        );
    }
}

Le provider ne connaît ni Order ni order : il sert toute ressource dont l'entité suit un workflow. Une machine à états reçoit des flèches étiquetées, un workflow des nœuds de transition, comme avec workflow:dump.

La ressource de la commande est un DTO séparé de son entité, plat, donc mappé par ObjectMapper :

// 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 App\Entity\Order;
use App\State\WorkflowDiagramProvider;
use Symfony\Component\ObjectMapper\Attribute\Map;

#[ApiResource(
    shortName: 'Order',
    operations: [
        new GetCollection(),
        new Get(),
        // Après le Get principal : l'IRI d'une commande vient du premier Get.
        new Get(
            uriTemplate: '/orders/{id}/workflow',
            output: WorkflowDiagram::class,
            provider: WorkflowDiagramProvider::class,
            map: false,
        ),
    ],
    stateOptions: new Options(entityClass: Order::class),
)]
#[Map(source: Order::class)]
final readonly class OrderResource
{
    // ... propriétés de la commande ...
}

Pour une commande payée, le champ mermaid contient :

%% GET /orders/{id}/workflow, champ mermaid
graph LR
place0(["draft"])
place1(("placed"))
place2(("paid"))
style place2 stroke-width:4px
place3(("shipped"))
place4(("cancelled"))
place0-->|"place"|place1
place1-->|"pay"|place2
place2-->|"ship"|place3
place1-->|"cancel"|place4
place2-->|"cancel"|place4

Rendu par mermaid.js : la place courante de la commande est encadrée Champ mermaid de GET /orders/{id}/workflow , commande payée draft place initiale placed shipped cancelled paid place courante place pay ship cancel cancel Le client dessine le texte reçu, sans connaître le workflow.

Le piège

Charger l'entité par le provider Doctrine d'API Platform. Un find() contournerait les extensions de requête, comme celle qui limite un client à ses commandes. Avec le provider intégré, une commande non lisible donne null, donc une 404. Une règle security qui teste object verrait en revanche le diagramme, pas la commande.

Désactiver le mapping : map: false. Quand la classe de la ressource porte #[Map], API Platform active ObjectMapper sur chacune de ses opérations, celle-ci comprise. ObjectMapperProvider, qui décore le localisateur des providers, repasserait alors le diagramme dans ObjectMapper. C'est une copie inutile, soumise à des règles qui changent entre versions.

Déclarer l'opération après le Get principal. API Platform génère l'IRI d'un objet depuis le premier Get déclaré. Placée avant, elle fournirait l'IRI des commandes dans les listes et les relations : /orders/{id}/workflow.

Retirer l'enveloppe TraceableWorkflow. En mode debug, actif par défaut hors de l'environnement prod, chaque workflow est enveloppé pour le profiler. instanceof StateMachine échoue alors, et les tests verraient un autre diagramme que la production. getInner() rend l'objet réel, comme dans workflow:dump.

Sources

Code relu le 15 novembre 2026 dans API Platform 4.3.18 et 5.0.7, Symfony 7.4.23 et 8.1.8 : identique sur ces points.