The problem
The order service moves each order through
a Symfony state machine named order. Its places are draft, placed,
paid, shipped and
cancelled, read from
Order::$status.
The back office shows where an order stands; an agent calling the API looks for the remaining steps. Copying places and transitions into each client creates a second source of truth, which drifts as soon as a transition is added.
The solution
Symfony can already draw a workflow:
workflow:dump --dump-format=mermaid and the
profiler's Workflow panel both rely on
MermaidDumper. Its dump() method
also takes a marking: each current place gets the
stroke-width:4px style.
We serve that text through an API Platform operation,
GET /orders/{id}/workflow. The client hands it
to mermaid.render() without knowing anything
about the workflow. The examples target API Platform 4.3 and
Symfony 7.4 or 8.1.
// src/ApiResource/WorkflowDiagram.php
namespace App\ApiResource;
final readonly class WorkflowDiagram
{
public function __construct(
public string $name,
// Mermaid flowchart, current places outlined.
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
{
// Loaded like the resource's Get, Doctrine extensions included.
$subject = $this->itemProvider->provide($operation, $uriVariables, $context);
if (null === $subject) {
return null; // API Platform answers 404.
}
$workflow = $this->workflows->get($subject);
// In debug, the registry returns a TraceableWorkflow, which hides the actual type.
$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)),
);
}
}
The provider knows neither Order nor
order: it serves any resource whose entity
follows a workflow. A state machine gets labelled arrows, a
workflow gets transition nodes, as with
workflow:dump.
The order resource is a DTO separate from its entity, flat, hence mapped by 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(),
// After the main Get: an order's IRI comes from the first 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
{
// ... properties of the order ...
}
For a paid order, the mermaid field holds:
%% GET /orders/{id}/workflow, mermaid field
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
The pitfall
Load the entity through API Platform's Doctrine
provider.
A find() would bypass the query extensions,
such as the one that limits a customer to their own orders.
With the built-in provider, an order the user may not read
gives null, hence a 404. A
security rule that tests object,
however, would see the diagram, not the order.
Turn mapping off: map: false.
When the resource class carries #[Map], API
Platform enables ObjectMapper on each of its operations,
this one included. ObjectMapperProvider, which
decorates the provider locator, would then run the diagram
through ObjectMapper again. That is a useless copy, subject
to rules that change between versions.
Declare the operation after the main
Get.
API Platform generates an object's IRI from the first
declared Get. Placed before it, it would
provide the IRI of orders in lists and relations:
/orders/{id}/workflow.
Unwrap the TraceableWorkflow.
In debug mode, on by default outside the
prod environment, each workflow is wrapped for
the profiler. instanceof StateMachine then
fails, and the tests would see a different diagram from
production. getInner() returns the actual
object, as workflow:dump does.
Sources
Code read on 15 November 2026 in API Platform 4.3.18 and 5.0.7, Symfony 7.4.23 and 8.1.8: identical on these points.
-
Symfony,
How to Dump Workflows:
workflow:dump, themermaidformat, current places as arguments. - Symfony, code of 8.1.8: MermaidDumper, WorkflowDumpCommand, TraceableWorkflow, WorkflowDebugPass, FrameworkBundle (pass added in debug), WorkflowDataCollector (profiler) and Dotenv (debug default).
-
API Platform,
Operations
(IRI from the first
Get), State Providers and Extensions. -
API Platform, code of 4.3.18:
ObjectMapperProvider,
ObjectMapperMetadataCollectionFactory
(
map), ItemProvider, ReadProvider, AccessCheckerProvider and IriConverter. -
Mermaid,
Flowcharts
and
Usage: shapes,
style,mermaid.render(). - Lychen, pull request 237: an open-source implementation of what this note describes, in a moon monorepo.