Symfony Workflow

Symfony Workflow is a standalone PHP component that lets you describe the lifecycle of your domain objects as an explicit state machine or Petri net. You define places (states) and transitions in a declarative Definition, attach a marking store that reads and writes the current state on your object, and the component enforces which transitions are legal, blocks disallowed ones, and dispatches events at every step.

Because a workflow can hold multiple simultaneous places, it models both simple single-state machines and complex multi-token Petri nets. Guards let you gate transitions on business rules or security, and the event system makes it easy to run side effects such as sending notifications or updating audit logs when an object moves from one state to another.

What You Get

• A declarative Definition of places and transitions built via DefinitionBuilder
• Two workflow types: single-state StateMachine and multi-token Workflow (Petri net)
• Pluggable marking stores that persist the current state on your objects
• A guard and event system for enforcing business rules and running side effects
• A Registry and support strategies for selecting the right workflow per subject
• Dumpers that render workflows as Graphviz, Mermaid, or PlantUML diagrams

Common Use Cases

• Managing an order or invoice lifecycle (draft, pending, paid, shipped)
• Content publishing pipelines with review and approval stages
• Modeling multi-step onboarding or application processes
• Enforcing which actions a user can take on an entity given its current state

Under The Hood

Architecture - The core Workflow class (implementing WorkflowInterface) is driven by an immutable Definition of places and Transition objects produced by DefinitionBuilder. Current state lives outside the workflow in a MarkingStore (typically MethodMarkingStore), which reads and writes a Marking onto the subject object, so the workflow itself stays stateless. apply(), can(), and getEnabledTransitions() consult the definition and marking, and a Registry with support strategies resolves which workflow applies to a given subject.

Tech Stack - Pure PHP targeting 8.4+, autoloaded via PSR-4 under Symfony\Component\Workflow. It has no hard runtime dependencies beyond PHP; optional Symfony components (event-dispatcher for events, expression-language for guard expressions, dependency-injection, validator, console) unlock extra features when present. Build and tooling follow the standard Symfony component conventions with composer.json and phpunit.xml.dist.

Code Quality - The repository ships a comprehensive Tests/ tree that mirrors the source layout, exercising definitions, marking stores, guards, dumpers, and the metadata store under PHPUnit. Interfaces are used consistently (WorkflowInterface, MarkingStoreInterface, MetadataStoreInterface), exceptions are namespaced and specific, and the code follows Symfony’s strict coding standards.

API Design - The public surface is small and intention-revealing: build a definition, pick a marking store, and call apply/can/getEnabledTransitions. Guards and side effects attach through the event system rather than subclassing, and the same object can be a state machine or a Petri net by choosing the workflow type. Extensive official documentation on symfony.com compensates for a deliberately terse README.