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
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.
-
Symfony,
How to Dump Workflows :
workflow:dump, formatmermaid, places courantes en argument. - Symfony, code de la 8.1.8 : MermaidDumper, WorkflowDumpCommand, TraceableWorkflow, WorkflowDebugPass, FrameworkBundle (passe ajoutée en debug), WorkflowDataCollector (profiler) et Dotenv (debug par défaut).
-
API Platform,
Operations
(IRI depuis le premier
Get), State Providers et Extensions. -
API Platform, code de la 4.3.18 :
ObjectMapperProvider,
ObjectMapperMetadataCollectionFactory
(
map), ItemProvider, ReadProvider, AccessCheckerProvider et IriConverter. -
Mermaid,
Flowcharts
et
Usage : formes,
style,mermaid.render(). - Lychen, pull request 237 : une mise en œuvre open source de ce que décrit cette note, dans un monorepo moon.