Download the PHP package rasuvaeff/yii3-workflow without Composer

rasuvaeff/yii3-workflow

Yii3 integration for symfony/workflow: the wiring Symfony's FrameworkBundle provides, plus the two things the component deliberately leaves out — a transition history and replay protection.

Using an AI coding assistant? llms.txt is a compact API reference designed for LLMs. Projects using the llm/skills Composer plugin also get this package's agent skill synced into .agents/skills/ automatically on install.

Русская версия

What it does

• Workflows by name. Definitions live in params.php; WorkflowRegistry builds them lazily and hands them out from the container.
• Enum marking store. Reads and writes a backed-enum status property of any visibility, so an aggregate does not need a public setter to be workflow-aware.
• PSR-14, not Symfony's dispatcher. Guards and reactions are ordinary listeners on the workflow event classes, dispatched through the application's own PSR-14 dispatcher (yiisoft/event-dispatcher). The package depends on the event-dispatcher contracts, not on an implementation.
• Audit trail. symfony/workflow stores only the current marking; this package records one row per committed transition through a TransitionLog seam you bind to your storage.
• Idempotency. applyOnce($subject, $transition, $key) skips a transition whose key is already in the log — the answer to a double-submitted form. Two lines of defence: a pre-flight lookup, and the log's own uniqueness constraint, which decides a race the lookup cannot.
• Eager validation. Definitions are checked with Symfony's own validators when a workflow is built, so a transition that could never fire is an error, not a silent no-op.
• workflow:dump. A console command rendering any configured workflow as Mermaid, PlantUML or Graphviz.

Requirements

• PHP 8.3 / 8.4 / 8.5
• symfony/workflow ^6.4 / ^7.0 / ^8.0
• psr/clock, psr/event-dispatcher, symfony/event-dispatcher-contracts
• symfony/console (for the dump command), yiisoft/definitions

Installation

yiisoft/config picks the package up automatically. Nothing else is bound by default — see Audit trail for the one binding you may want to add.

Configuration

Places and transition endpoints accept backed enums or plain strings. In a state machine a transition with several sources is expanded into one transition per source — the same normalisation Symfony's YAML config performs.

Metadata is declarative too — it lands in the definition's metadata store, readable by guards (getMetadataStore()) and rendered by the dumpers:

A placesMetadata key that names an unknown place is an error, not silently dead configuration.

Usage

A key is scoped to (workflow, subject), not to a transition: reusing a key on the same subject with a different transition is reported as a replay (false), so keys must be unique per operation. applyOnce() refuses a key its wiring cannot honour — no TransitionLog, no IdempotencyContext, or an AuditListener that never recorded the key — with a LogicException instead of silently applying without protection.

With a persistent log the audit row is written inside apply(): run applyOnce() and your save() in one database transaction. Otherwise a failed save burns the key — the log says the transition happened, the entity never changed, and every retry is skipped as a replay. See the yii3-workflow-db README for the recipe — that package also ships a WorkflowTransaction helper that makes it a single call.

Every skipped replay is also dispatched to the application's PSR-14 dispatcher as an Audit\TransitionReplayed event (workflow, subject id, transition, key, and whether the pre-flight lookup or the storage constraint decided), so replays can be counted and logged instead of disappearing into a false.

Guards and reactions

Every workflow event reaches the application's PSR-14 dispatcher exactly once — under the generic name, not once per workflow.<name>.<event> variant — so a class-based listener is not called three times. Guard listeners therefore run for every workflow of the application; extend TransitionGuard and the "is this my workflow, is this my transition" filtering is done for you:

A plain PSR-14 listener on the event class still works — the base class only removes the filtering ritual.

Register it like any other Yii3 listener (config/common/events-web.php). The blocker's message and code come back through blockers(), so an API can tell the user why an action is unavailable.

Audit trail

TransitionLog is deliberately not bound by this package — exactly like yiisoft/cache leaves Psr\SimpleCache\CacheInterface to a backend. Without a binding the workflows still run and record nothing; passing an idempotency key in that state is refused with a LogicException rather than silently doing nothing.

Install rasuvaeff/yii3-workflow-db for a yiisoft/db implementation with the migration, or bind your own:

An implementation stores TransitionRecord::toArray() rows and answers hasIdempotencyKey(). InMemoryTransitionLog ships for tests and one-off scripts.

Dumping a diagram

WorkflowDumpCommand is registered as workflow:dump through params.php:

The diagram flavour follows the configured type: a state_machine is drawn with direct edges between places, a Petri-net workflow with explicit transition nodes.

Security

The package performs no I/O of its own: it moves a marking on an object you pass in and hands audit rows to your TransitionLog. Transition and place names come from your configuration, never from user input — keep it that way, since a name reaching apply() selects behaviour. Guard listeners are the place for authorisation checks; a transition without a guard is allowed for anyone who can reach the handler.

Examples

See examples/ for a runnable script covering the whole loop.

Development

No PHP or Composer on the host — every target runs inside the composer:2 Docker image.

License

BSD-3-Clause. See LICENSE.md.