The document describes state machines and their use in modeling application workflows and business processes. State machines define a set of states, transitions between states, and rules governing the transitions. They allow enforcing business logic by validating transitions and triggering actions on transitions. The document discusses several PHP libraries for implementing state machines, including WinzouStateMachine, Symfony Workflow, and Finite. It provides examples of using callbacks and guards to add validation and trigger external services during state transitions. In summary, state machines help define and enforce business rules by modeling the valid states and transitions of an entity.

1. A SHORT TALE
ABOUT
STATE MACHINE

2. @lukaszchrusciel
Albert

3. @lukaszchrusciel
Once upon a time…

4. @lukaszchrusciel

5. final class Payment
{
/** @var bool */
private $pending = false;
}

6. @lukaszchrusciel

7. @lukaszchrusciel
A few days later

8. @lukaszchrusciel

9. final class Payment
{
/** @var bool */
private $pending = false;
/** @var bool */
private $failed = false;
}

10. @lukaszchrusciel

11. final class Payment
{
/** @var bool */
private $pending = false;
/** @var bool */
private $failed = false;
}

12. final class Payment
{
public const NEW = 1;
public const PENDING = 2;
public const FAILED = 3;
/** @var int */
private $state = self::NEW;
}
?

14. @lukaszchrusciel
State Machine

15. @lukaszchrusciel
(Q, Σ, δ, q0, F)
Q = a finite set of states
Σ = a finite, nonempty input alphabet
δ = a series of transition functions
q0 = the starting state
F = the set of accepting states

16. @lukaszchrusciel
NEW
PENDING
FAILED PAID
Create
PayFail

17. @lukaszchrusciel
Libraries

18. @lukaszchrusciel
What can we do with it?
Define possible states and relation between them
Protect business rules (with guards)
Trigger other services on transitions

19. @lukaszchrusciel
WinzouStateMachine

20. @lukaszchrusciel
Callback’s execution in config file
Used heavily in Sylius
Configurable arguments of service
Services have to be public in order to make it work
Lack of documentation
Not stable

21. winzou_state_machine:
payment:
class: AppModelPayment
property_path: state
graph: payment
states:
new: ~
pending: ~
failed: ~
paid: ~
transitions:
process:
from: [new]
to: pending
fail:
from: [pending]
to: failed
pay:
from: [pending]
to: paid

22. winzou_state_machine:
payment:
class: AppModelPayment
property_path: state
graph: payment
states:
new: ~
pending: ~
failed: ~
paid: ~
transitions:
process:
from: [new]
to: pending
fail:
from: [pending]
to: failed
pay:
from: [pending]
to: paid

23. winzou_state_machine:
payment:
class: AppModelPayment
property_path: state
graph: payment
states:
new: ~
pending: ~
failed: ~
paid: ~
transitions:
process:
from: [new]
to: pending
fail:
from: [pending]
to: failed
pay:
from: [pending]
to: paid

24. winzou_state_machine:
payment:
class: AppModelPayment
property_path: state
graph: payment
states:
new: ~
pending: ~
failed: ~
paid: ~
transitions:
process:
from: [new]
to: pending
fail:
from: [pending]
to: failed
pay:
from: [pending]
to: paid

25. @lukaszchrusciel
Symfony Workflow

26. @lukaszchrusciel
Maintained by Symfony
Flex support
Workflow & state machine support
Execution of external services with events
XML / YAML / PHP support out-of-the-box

27. framework:
workflows:
payment:
type: 'state_machine'
supports:
- AppModelPayment
initial_marking: new
marking_store:
type: method
property: state
places:
- new
- pending
- failed
- paid
transitions:
process:
from: new
to: pending
fail:
from: pending
to: failed
pay:
from: pending
to: paid

28. framework:
workflows:
payment:
type: 'state_machine'
supports:
- AppModelPayment
initial_marking: new
marking_store:
type: method
property: state
places:
- new
- pending
- failed
- paid
transitions:
process:
from: new
to: pending
fail:
from: pending
to: failed
pay:
from: pending
to: paid

29. framework:
workflows:
payment:
type: 'state_machine'
supports:
- AppModelPayment
initial_marking: new
marking_store:
type: method
property: state
places:
- new
- pending
- failed
- paid
transitions:
process:
from: new
to: pending
fail:
from: pending
to: failed
pay:
from: pending
to: paid

30. framework:
workflows:
payment:
type: 'state_machine'
supports:
- AppModelPayment
initial_marking: new
marking_store:
type: method
property: state
places:
- new
- pending
- failed
- paid
transitions:
process:
from: new
to: pending
fail:
from: pending
to: failed
pay:
from: pending
to: paid

31. @lukaszchrusciel
Finite

32. @lukaszchrusciel
Oldest and most popular implementation (in terms of stars)
Extendability with events & callbacks definition
It is said to be little bit heavier implementation compared to
Winzou

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

34. @lukaszchrusciel
WinzouStateMachine

35. final class SomeService
{
public function __construct(FactoryInterface $factory)
{
$this->factory = $factory;
}
public function doStuff(): void
{
$stateMachine = $this->factory->get($payment, 'payment');
$stateMachine->apply('process');
$stateMachine->apply(‘fail');
}
}

36. @lukaszchrusciel
Symfony Workflow

37. final class SomeService
{
public function __construct(Registry $workflows)
{
$this->workflows = $workflows;
}
public function doStuff(): void
{
$stateMachine = $this->workflows->get($payment, 'payment');
$stateMachine->apply($payment, 'process');
$stateMachine->apply($payment, ‘fail');
}
}

38. @lukaszchrusciel

39. @lukaszchrusciel

40. @lukaszchrusciel
New adventures

41. @lukaszchrusciel

42. @lukaszchrusciel
WinzouStateMachine

43. AppOperatorInventoryOperator:
public: true
final class InventoryOperator
{
public function __invoke(Payment $payment): void
{
// Reduce inventory of bought products
}
}
winzou_state_machine:
payment:
…
callbacks:
before:
reduce_amount:
on: ["pay"]
do: [“@AppOperatorInventoryOperator”, "__invoke"]
args: [“object"] # <- Expression language can be used

44. AppOperatorInventoryOperator:
public: true
final class InventoryOperator
{
public function __invoke(Payment $payment): void
{
// Reduce inventory of bought products
}
}
winzou_state_machine:
payment:
…
callbacks:
before:
reduce_amount:
on: ["pay"]
do: [“@AppOperatorInventoryOperator”, "__invoke"]
args: [“object"] # <- Expression language can be used

45. @lukaszchrusciel
Callbacks types
Guard
Before
After

46. AppOperatorInventoryOperator:
public: true
final class InventoryOperator
{
public function __invoke(Payment $payment): void
{
// Reduce inventory of bought products
}
}
winzou_state_machine:
payment:
…
callbacks:
before:
reduce_amount:
on: ["pay"]
do: [“@AppOperatorInventoryOperator”, "__invoke"]
args: [“object"] # <- Expression language can be used

47. @lukaszchrusciel
Callbacks types
On -> transition
From -> state
To -> state

48. @lukaszchrusciel
Symfony Workflow

49. final class PaymentPaidListener
{
public function __invoke(EnterEvent $event): void
{
// Reduce inventory of bought products
}
}
AppEventListenerAfterPaymentPaidListener:
tags:
- name: kernel.event_listener
event: workflow.payment.entered.paid
method: __invoke

50. @lukaszchrusciel
Actions
workflow.[transition type]
workflow.[workflow name].[transition type]
workflow.[workflow name].[transition type].[transition name]

51. @lukaszchrusciel
Types for transitions
guard
transition
completed
announce

52. @lukaszchrusciel
Actions
workflow.[place type]
workflow.[workflow name].[place type]
workflow.[workflow name].[place type].[place name]

53. @lukaszchrusciel
Types for places
leave
enter
entered

54. @lukaszchrusciel

55. @lukaszchrusciel

56. @lukaszchrusciel
Symfony Workflow

57. @lukaszchrusciel
#1

58. final class BlockedGuardListener
{
public function __invoke(GuardEvent $event): void
{
$event->setBlocked(true);
}
}
AppEventListenerBlockedGuardListener:
tags:
- name: kernel.event_listener
event: workflow.payment.guard.block
method: __invoke

59. @lukaszchrusciel

60. @lukaszchrusciel
#2

61. framework:
workflows:
payment:
...
transitions:
...
block:
guard: "is_granted('ROLE_ADMIN')"
from: pending
to: blocked

62. symfony/security-core

63. @lukaszchrusciel

64. @lukaszchrusciel
WinzouStateMachine

65. AppAuthorizerBlockedAuthorizer:
public: true
final class BlockAuthorizer
{
public function __invoke(): bool
{
return false;
}
}
winzou_state_machine:
payment:
...
callbacks:
guard:
guard-blocked:
to: ["blocked"]
do: ["@AppAuthorizerBlockedAuthorizer", "__invoke"]

66. @lukaszchrusciel

67. @lukaszchrusciel

68. @lukaszchrusciel
Final boss

69. @lukaszchrusciel

70. final class AfterPaymentPaidListener
{
public function __invoke(EnteredEvent $event): void
{
/** @var Payment $payment */
$payment = $event->getSubject();
file_get_contents(
'https://workflow.free.beeceptor.com?state=' . $payment->getState()
);
}
}
AppEventListenerAfterPaymentPaidListener:
tags:
- name: kernel.event_listener
event: workflow.payment.entered.paid
method: __invoke

71. @lukaszchrusciel
But when do you flush?

72. final class InformAboutPaidPayment
{...}
final class InformAboutPaidPaymentHandler implements MessageHandlerInterface
{
public function __invoke(InformAboutPaidPayment $payment)
{
// Check if it should be dispatched
file_get_contents(
‘https://workflow.free.beeceptor.com?state='. $payment->getSubject()
);
}
}
MESSENGER_TRANSPORT_DSN=doctrine://default

73. @lukaszchrusciel

74. @lukaszchrusciel
Summary

75. @lukaszchrusciel
Define 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

77. @lukaszchrusciel
Common issues

78. @lukaszchrusciel
Business logic wired up in configuration files

79. @lukaszchrusciel
Describe problem with state machine
but implement directly in code

80. @lukaszchrusciel
Possibility to destroy state of entities
if state machine is omitted

81. @lukaszchrusciel

82. @lukaszchrusciel
😭

83. setState(…)

84. @lukaszchrusciel
Informing external system on transition callback

85. @lukaszchrusciel
Dispatching messages
on transition callbacks is not the best idea.
Defer external calls and ensure proper state.

86. @lukaszchrusciel
https://github.com/lchrusciel/StateMachine
Thank you!