State Machine

Provides code-driven workflow functionality.

A workflow is a set of states and transitions that an entity goes through during its lifecycle. A transition represents a one-way link between two states and has its own label.

Drupal 8

Workflows and workflow groups are plugins defined in YAML, similar to menu links.

The current state is stored in a special field type (StateItem), which references the used workflow, and acts as a state machine. It has an API for getting the allowed transitions:

$order_state = $order->getState();
print $order_state->value; // fulfillment
// Get the allowed transitions for the current state.
$transitions = $order_state->getTransitions();
// All transitions have a translatable label that can be shown in the UI (great for action buttons)
// Same as $order_state->value = 'completed';

An entity can have multiple workflows, each in its own state field. An order might have checkout and payment workflows. A node might have legal and marketing workflows. Workflow groups are used to group workflows used for the same purpose (e.g. payment workflows).

See the documentation for a full architecture overview.

Drupal 7

The State Flow submodule provides a base implementation of the State Machine class. It provides a base workflow as a base plugin.

Custom plugins should use State Flow as a model when:

  • Adding new states
  • Adding new events

State Flow provides the following optional integration with other modules:

  • Rules: Hook a condition into a event transition
  • Views: Exposes defined states, revision information, and timestamps

There are two active branches:


  • Extend State Flow by hook_state_flow_machine_type_alter() instead of variable_set
  • Bulk revision editing
  • Workflow scheduling. Requires Date_Popup.
  • Easily implement conditions to allow workflow to be ignored


Currently in unstable development as a collaborative effort with Workbench Moderation. State Flow will become State Flow Node. An entity agnostic State Flow Entity will be created. State Flow Node will be dependent on State Flow Entity.
Uses Drafty to ensure consistent revision handling.
More info on 3.x #1587574: [META] Merge changes from 2.x and 3.x

Development sponsored by

This module was also made with PHPStorm, an awesome IDE from Jetbrains that provides licenses supporting open source projects and Navicat, an equally awesome database management GUI.

Supporting organizations: 
Sponsorship of the D8 version
Sponsorship of the D7 version

Project Information