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

Rendered by mermaid.js: the order's current place is outlined The mermaid field of GET /orders/{id}/workflow , for a paid order draft initial place placed shipped cancelled paid current place place pay ship cancel cancel The client draws the text it receives, without knowing the workflow.

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.