State machine is a powerful concept. How can it be used in php? What is the difference between libraries?

1. A SHORT TALE
ABOUT
STATE MACHINE

2. Albert

3. Once upon a time…

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

7. A few days later

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

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 = 1;
public const FAILED = 2;
/** @var int */
private $state = self::NEW;
}
?

14. State Machine

15. (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. NEW
PENDING
FAILED PAID
Create
PayFail

17. Libraries

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

19. WinzouStateMachine

20. 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. Symfony Workflow

26. 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
paying:
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
paying:
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
paying:
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
paying:
from: pending
to: paid

31. Finite

32. 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

35. New adventures

37. Symfony Workflow

38. final class PaymentPaidListener
{
public function __invoke(EnterEvent $event): void
{
$payment = $event->getSubject();
// Reduce inventory of bought products
}
}
AppEventListenerPaymentPaidListener:
tags:
- name: kernel.event_listener
event: workflow.payment.enter.paid
method: __invoke

39. Actions
workflow.[type]
workflow.[workflow name].[type]
workflow.[workflow name].[type].[transition name]

40. Types for transitions
guard
transition
completed
announce

41. Actions
workflow.[type]
workflow.[workflow name].[type]
workflow.[workflow name].[type].[place name]

42. Types for places
leave
enter
entered

43. WinzouStateMachine

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. Callbacks types
Before
After
Guard

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

49. Symfony Workflow

50. #1

51. 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

53. #2

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

55. symfony/security-core

57. WinzouStateMachine

58. 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"]

62. 😭

63. Final boss

65. 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

66. But when do you flush?

67. 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

69. Summary

70. Define possible states and relation between them
Protect business rules (with guards)
Trigger other services on transitions
Trigger other state changes as a reaction

72. Common issues

73. Business logic wired up in configuration files

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

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

76. setState(…)

77. Informing external system on transition callback

78. Sending emails or dispatching messages
on transition callbacks is not the best idea.
Defer external calls and ensure proper state.

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

80. https://github.com/lchrusciel/StateMachine
@lukaszchrusciel
Q & A

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