Entities lifecycle is usually something more than create and delete. Models with which we are working on day to day basis change their state under some business circumstances. State machine patterns can be a powerful allay when solving this kind of problem. How does it look like? What are the pros and cons of state machine usage? What are the things that we should be beware of? I will answer these questions during my talk, together with practical differences between the most popular implementation.

1. A SHORT TALE ABOUT
STATE MACHINE

2. Once upon a time…

3. Kelly

5. final class Payment
{
private bool $pending = false;
}

7. Th
e end of chapter 1

8. A few days later

10. final class Payment
{
private bool $pending = false;
private bool $failed = false;
}

12. final class Payment
{
private bool $pending = false;
private bool $failed = false;
}

13. final class Payment
{
public const NEW = 1;
public const PENDING = 2;
public const FAILED = 3;
private int $state = self::NEW;
}
?

15. State Machine

16. (Q, Σ, δ, q0, F)
Q = a
fi
nite set of states
Σ = a
fi
nite, nonempty input alphabet
δ = a series of transition functions
q0 = the starting state
F = the set of accepting states

17. NEW
PENDING
FAILED PAID
Create
Pay
Fail

18. Let’s do the research!

19. De
fi
ne possible states and relation between them
Protect business rules
Integrate other services on transitions
What do we expect?

20. WinzouStateMachine

21. Callback’s execution in con
fi
g
fi
le
Used heavily in Sylius
Con
fi
gurable arguments of service
Services have to be public in order to integrate them with state machine
Without stable release, yet battle-tested and robust

24. $config =
[
'graph' => 'payment'
,
'property_path' => 'state'
,
'states' => ['new','pending','failed','paid']
,
'transitions' =>
[
'process' =>
[
'from' => ['new']
,
'to' => 'pending'
,
]
,
'fail' =>
[
'from' => ['pending']
,
'to' => 'failed'
,
]
,
'pay' =>
[
'from' => ['pending']
,
'to' => 'paid'
,
]
,
]
,
];

25. $config =
[
'graph' => 'payment'
,
'property_path' => 'state'
,
'states' => ['new','pending','failed','paid'],
'transitions' =>
[
'process' =>
[
'from' => ['new']
,
'to' => 'pending'
,
]
,
'fail' =>
[
'from' => ['pending']
,
'to' => 'failed'
,
]
,
'pay' =>
[
'from' => ['pending']
,
'to' => 'paid'
,
]
,
]
,
];

26. $config =
[
'graph' => 'payment'
,
'property_path' => 'state',
'states' => ['new','pending','failed','paid']
,
'transitions' => [
'process' =>
[
'from' => ['new']
,
'to' => 'pending'
,
]
,
'fail' =>
[
'from' => ['pending']
,
'to' => 'failed'
,
]
,
'pay' =>
[
'from' => ['pending']
,
'to' => 'paid'
,
]
,
]
,
];

27. $config =
[
'graph' => 'payment'
,
'property_path' => 'state'
,
'states' => ['new','pending','failed','paid'],
'transitions' =>
[
'process' =>
[
'from' => ['new']
,
'to' => 'pending'
,
]
,
'fail' =>
[
'from' => ['pending']
,
'to' => 'failed'
,
]
,
'pay' =>
[
'from' => ['pending']
,
'to' => 'paid'
,
]
,
]
,
];

28. Symfony Work
fl
ow

29. Maintained by Symfony
Flex support
Work
fl
ow & state machine support
Execution of external services with events
XML / YAML / PHP support out-of-the-box
Best documentation hands down

32. $definitionBuilder = new DefinitionBuilder()
;
$definition = $definitionBuilder->addPlaces(['new','pending','failed','paid']
)
->addTransition(new Transition('process', 'new', 'pending')
)
->addTransition(new Transition('fail', [‘pending'], 'failed')
)
->addTransition(new Transition('pay', 'pending', 'paid')
)
->build(
)
;
$singleState = true
;
$property = 'state'
;
$marking = new MethodMarkingStore($singleState, $property)
;
$workflow = new Workflow($definition, $marking, null, 'payment');

33. $definitionBuilder = new DefinitionBuilder()
;
$definition = $definitionBuilder->addPlaces(['new','pending','failed','paid']
)
->addTransition(new Transition('process', 'new', 'pending')
)
->addTransition(new Transition('fail', ['pending'], 'failed')
)
->addTransition(new Transition('pay', 'pending', 'paid')
)
->build(
)
;
$singleState = true
;
$property = 'state'
;
$marking = new MethodMarkingStore($singleState, $property)
;
$workflow = new Workflow($definition, $marking, null, 'payment');

34. $definitionBuilder = new DefinitionBuilder()
;
$definition = $definitionBuilder->addPlaces(['new','pending','failed','paid']
)
->addTransition(new Transition('process', 'new', 'pending')
)
->addTransition(new Transition('fail', [‘pending'], 'failed')
)
->addTransition(new Transition('pay', 'pending', 'paid')
)
->build(
)
;
$singleState = true
;
$property = 'state'
;
$marking = new MethodMarkingStore($singleState, $property)
;
$workflow = new Workflow($definition, $marking, null, 'payment');

35. Finite

36. Oldest and most popular implementation
(in terms of stars)
Least used implementation
(in terms of daily installs according to packagist)
Extendability with events & callbacks de
fi
nition
Perhaps reached its EOL
(https://github.com/yohang/Finite/issues/161)
It is said to be little bit heavier implementation compared to Winzou

39. Back to
the
st
ory…

40. final class Payment
{
public const NEW = 'new';
private string $state = self::NEW;
public function getState(): string
{
return $this->state;
}
public function setState(string $state): void
{
$this->state = $state
}
}

41. WinzouStateMachine

42. $payment = new Payment()
;
$stateMachine = new StateMachine($payment, $config)
;
$stateMachine->apply('process')
;
$stateMachine->apply('fail');

43. Symfony Work
fl
ow

44. $payment = new Payment()
;
$workflow->apply($payment, 'process')
;
$workflow->apply($payment, 'fail');

47. Th
e end of chapter 2

48. New adventur
e

50. WinzouStateMachine

51. final class InventoryOperato
r
{
public function __invoke(TransitionEvent $transitionEvent): voi
d
{
$stateMachine = $transitionEvent->getStateMachine()
;
/** @var Payment $payment *
/
$payment = $stateMachine->getObject()
;
// Reduce inventory of bought product
s
}
}
$config =
[
// ..
.
'callbacks' =>
[
'before' =>
[
'reduce_amount' =>
[
'on' => ['pay']
,
'do' => new InventoryOperator()
,
]
,
]
,
]
,
];

52. final class InventoryOperato
r
{
public function __invoke(TransitionEvent $transitionEvent): voi
d
{
$stateMachine = $transitionEvent->getStateMachine()
;
/** @var Payment $payment *
/
$payment = $stateMachine->getObject()
;
// Reduce inventory of bought product
s
}
}
$config =
[
// ..
.
'callbacks' =>
[
'before' =>
[
'reduce_amount' =>
[
'on' => ['pay']
,
'do' => new InventoryOperator()
,
]
,
]
,
]
,
];

53. final class InventoryOperato
r
{
public function __invoke(TransitionEvent $transitionEvent): voi
d
{
$stateMachine = $transitionEvent->getStateMachine()
;
/** @var Payment $payment *
/
$payment = $stateMachine->getObject()
;
// Reduce inventory of bought product
s
}
}
$config =
[
// ..
.
'callbacks' => [
'before' => [
'reduce_amount' =>
[
'on' => ['pay']
,
'do' => new InventoryOperator()
,
]
,
]
,
]
,
];

54. Guard
Before
After
Callbacks types
* Same can be achieved with dispatched events

55. class StateMachine implements StateMachineInterface
{
public function apply(/** */): void
{
// Guard callback
if (!$this->can($transition)) {
throw new SMException();
}
// Before callback
$this->setState('failed');
// After callback
}
}

56. final class InventoryOperato
r
{
public function __invoke(TransitionEvent $transitionEvent): voi
d
{
$stateMachine = $transitionEvent->getStateMachine()
;
/** @var Payment $payment *
/
$payment = $stateMachine->getObject()
;
// Reduce inventory of bought product
s
}
}
$config =
[
// ..
.
'callbacks' =>
[
'before' =>
[
'reduce_amount' => [
'on' => ['pay']
,
'do' => new InventoryOperator()
,
]
,
]
,
]
,
];

57. On -> transition
From -> state
To -> state
Callbacks types

58. Symfony Work
fl
ow

59. $dispatcher = new EventDispatcher()
;
$dispatcher->addListener
(
'workflow.payment.enter.paid',
new PaymentPaidListener(
)
)
;
$workflow = new Workflow($definition, $marking, $dispatcher, 'payment');
final class PaymentPaidListener
{
public function __invoke(EnterEvent $event): void
{
// Reduce inventory of bought products
}
}

60. $dispatcher = new EventDispatcher()
;
$dispatcher->addListener
(
'workflow.payment.enter.paid',
new PaymentPaidListener(
)
);
$workflow = new Workflow($definition, $marking, $dispatcher, 'payment');
final class PaymentPaidListener
{
public function __invoke(EnterEvent $event): void
{
// Reduce inventory of bought products
}
}

61. $dispatcher = new EventDispatcher()
;
$dispatcher->addListener(
'workflow.payment.enter.paid',
new PaymentPaidListener(
)
)
;
$workflow = new Workflow($definition, $marking, $dispatcher, 'payment');
final class PaymentPaidListener
{
public function __invoke(EnterEvent $event): void
{
// Reduce inventory of bought products
}
}

62. $dispatcher = new EventDispatcher()
;
$dispatcher->addListener(
'workflow.payment.enter.paid',
new PaymentPaidListener(
)
)
;
$workflow = new Workflow($definition, $marking, $dispatcher, 'payment');
final class PaymentPaidListener
{
public function __invoke(EnterEvent $event): void
{
// Reduce inventory of bought products
}
}

63. $dispatcher = new EventDispatcher()
;
$dispatcher->addListener(
'workflow.payment.enter.paid',
new PaymentPaidListener(
)
)
;
$workflow = new Workflow($definition, $marking, $dispatcher, 'payment');
final class PaymentPaidListener
{
public function __invoke(EnterEvent $event): void
{
// Reduce inventory of bought products
}
}

64. work
fl
ow.[place type]
work
fl
ow.[work
fl
ow name].[place type]
work
fl
ow.[work
fl
ow name].[place type].[place name]
Actions

65. leave -> current place
enter -> which place(places) will be visited
entered -> which place(places) were visited
Types for places

66. work
fl
ow.[transition type]
work
fl
ow.[work
fl
ow name].[transition type]
work
fl
ow.[work
fl
ow name].[transition type].[transition name]
Actions

67. guard -> possibility to validate transition
transition -> which transition will be executed
completed -> which transition was executed
announce -> which transition are available now
Types for transitions

68. class Workflow implements WorkflowInterface
{
public function apply(/** */
)
{
$this->leave(/** */)
;
$this->transition(/** */);
$this->enter(/** */)
;
/** Making transition */
$this->markingStore->setMarking($payment, 'failed', $context)
;
$this->entered(/** */)
;
$this->completed(/** */)
;
$this->announce(/** */)
;
}
}

71. WinzouStateMachine

72. final class BlockAuthorizer
{
public function __invoke(): bool
{
return false;
}
}
$config =
[
/** ... *
/
'callbacks' =>
[
/** ... *
/
'guard' =>
[
'guard-blocked' =>
[
'to' => ['blocked']
,
'do' => new BlockedAuthorizer()
,
]
,
]
,
]
,
];

73. Symfony Work
fl
ow

74. final class BlockedGuardListener
{
public function __invoke(GuardEvent $event): void
{
$event->setBlocked(true);
}
}
$dispatcher->addListener
(
'workflow.payment.guard.block'
,
new BlockedGuardListener(
)
)
;

76. Th
e end of chapter 3

77. Summary

78. De
fi
ne possible states and relation between them
Protect business rules (with guards)
Trigger other services on transitions
Ease to add new possible transitions
Trigger other state changes as a reaction

79. WinzouStateMachine vs Symfony Work
fl
ow

81. Why should you care?

82. Common issues

83. Business logic wired up in
con
fi
guration
fi
les

84. Describe problem with state machine
but implement directly in code

85. Possibility to destroy state of entities
if state machine is omitted

87. 😭

88. setState(…)

89. lchrusciel/RawStateMachine

90. @Sylius
Thank you!
@lukaszchrusciel