State Machines in Laravel

Determining the current state of an entity can be difficult. For many, determining state is always implicit — typically taking the form of booleans and timestamps littered throughout database columns and the codebase. The ever growing list of rules used to determine state are rarely documented and even less often tested. What can we do?

Simple state machines, allow us to make our state explicit and provide clear instructions on when and how that state should change. By making our state explicit, we can eliminate edge cases, write less code, and confidently test our implementations. The great news is that you don’t need to make large changes to benefit from this simple pattern!

During this talk, participants will learn:

- The event-state-action paradigm
- How to create a state chart / diagram
- How to implement a simple state machine
- How to refactor to a simple state machine from existing code

Transcript

1. Jake Bennett jacobbennett
3. Laravel News Podcast North Meets South
4. State Machines
5. Story Time
6. The Problem
7. The Pattern
8. The Implementation
9. The Problem
10. The Problem Invoice System
11. The Problem Building Block of our Software System Entity
12. The Problem Action Something that triggers a speci fi c response
13. The Problem class Invoice extends Model Entity
14. The Problem Actions Create - User creates an Invoice Edit - Update our Invoice Details Finalize - User fi nalizes Invoice to make it ready for payment Pay - Customer pays the Invoice
15. class InvoiceController extends Controller { public function store(CreateInvoiceRequest $request) { Invoice::create($request->validate()); return redirect()->route('invoice.index'); } public function update(UpdateInvoiceRequest $request, Invoice $invoice) { $invoice->update($request->validate()); return redirect()->route('invoice.show', $invoice); } }
16. class InvoiceController extends Controller { public function store(CreateInvoiceRequest $request) { Invoice::create($request->validate()); return redirect()->route('invoice.index'); } public function update(UpdateInvoiceRequest $request, Invoice $invoice) { $invoice->update($request->validate()); return redirect()->route('invoice.show', $invoice); } }
17. class InvoiceController extends Controller { public function store(CreateInvoiceRequest $request) { Invoice::create($request->validate()); return redirect()->route('invoice.index'); } public function update(UpdateInvoiceRequest $request, Invoice $invoice) { $invoice->update($request->validate()); return redirect()->route('invoice.show', $invoice); } }
18. class FinalizeInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { $invoice->update(['finalized_at' => now()]); Mail::send(new InvoiceDue($invoice)); return view('invoice.show', ['invoice' => $invoice]); } }
19. class PayInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { $invoice->update(['paid_at' => now()]); Mail::send(new InvoicePaid($invoice)); return view('invoice.thanks', ['invoice' => $invoice]); } }
20. class FinalizeInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { $invoice->update(['finalized_at' => now()]); Mail::send(new InvoiceDue($invoice)); return view('invoice.show', ['invoice' => $invoice]); } }
21. class InvoiceController extends Controller { // ... public function update(UpdateInvoiceRequest $request, Invoice $invoice) { $invoice->update($request->validate()); return redirect()->route('invoice.show', $invoice); } // ... }
22. class InvoiceController extends Controller { // ... public function update(UpdateInvoiceRequest $request, Invoice $invoice) { if (filled($invoice->finalized_at) || filled($invoice->paid_at)) { abort(403, 'Invoice cannot be updated’); } $invoice->update($request->validate()); return redirect()->route('invoice.show', $invoice); } // ... }
23. class InvoiceController extends Controller { // ... public function update(UpdateInvoiceRequest $request, Invoice $invoice) { if (filled($invoice->finalized_at) || filled($invoice->paid_at)) { abort(403, 'Invoice cannot be updated’); } $invoice->update($request->validate()); return redirect()->route('invoice.show', $invoice); } // ... }
24. class FinalizeInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { $invoice->update(['finalized_at' => now()]); Mail::send(new InvoiceDue($invoice)); return view('invoice.show', ['invoice' => $invoice]); } }
25. class FinalizeInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { if (filled($invoice->finalized_at) || filled($invoice->paid_at)) { abort(403, 'Invoice cannot be finalized'); } $invoice->update(['finalized_at' => now()]); Mail::send(new InvoiceDue($invoice)); return view('invoice.show', ['invoice' => $invoice]); } }
26. class FinalizeInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { if (filled($invoice->finalized_at) || filled($invoice->paid_at)) { abort(403, 'Invoice cannot be finalized'); } $invoice->update(['finalized_at' => now()]); Mail::send(new InvoiceDue($invoice)); return view('invoice.show', ['invoice' => $invoice]); } }
27. class PayInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { $invoice->update(['paid_at' => now()]); Mail::send(new InvoicePaid($invoice)); return view('invoice.thanks', ['invoice' => $invoice]); } }
28. class PayInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { if (blank($invoice->finalized_at) || filled($invoice->paid_at)) { abort(403, 'Invoice cannot be paid'); } $invoice->update(['paid_at' => now()]); Mail::send(new InvoicePaid($invoice)); return view('invoice.thanks', ['invoice' => $invoice]); } }
29. class PayInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { if (blank($invoice->finalized_at) || filled($invoice->paid_at)) { abort(403, 'Invoice cannot be paid'); } $invoice->update(['paid_at' => now()]); Mail::send(new InvoicePaid($invoice)); return view('invoice.thanks', ['invoice' => $invoice]); } }
30. The Problem
31. The Problem • Di ffi cult to determine what rules apply when • Duplication of logic every place we want to update Invoice • Code only ever grows in complexity… for example
32. The Problem New Actions Cancel - Invoices that are Uncollectable Void - Invoices sent accidently
33. The Problem What Needs to Change 1. Add new Flags for each Action 2. Add conditionals wherever we update Invoice
34. class PayInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { if (blank($invoice->finalized_at) || filled($invoice->paid_at)) { abort(403, 'Invoice cannot be paid'); } $invoice->update(['paid_at' => now()]); Mail::send(new InvoicePaid($invoice)); return view('invoice.thanks', ['invoice' => $invoice]); } }
35. class PayInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { if ( blank($invoice->finalized_at) || filled($invoice->paid_at) || filled($invoice->uncollectable_at) || filled($invoice->void_at) ) { abort(403, 'Invoice cannot be paid'); } $invoice->update(['paid_at' => now()]); Mail::send(new InvoicePaid($invoice));
36. The Problem
37. The Pattern
38. The Pattern What is a State Machine? a State Machine is a way to help us model how a process goes from one state to another state when an event occurs.
39. The Pattern What is a State Machine? A state machine is a way to help us to model our application logic.
40. The Pattern State Diagram
41. The Pattern State Diagram
42. The Pattern State Diagram
43. The Pattern State Diagram
44. The Pattern State Diagram
45. The Pattern State Diagram
46. The Pattern State Diagram
47. The Pattern State Diagram
48. The Pattern State Diagram
49. The Pattern State Diagram
50. The Pattern State Diagram
51. The Pattern State Diagram
52. The Pattern What is a State? A State, models how a system responds to events for a particular point in time.
53. The Pattern What is a State?
54. The Pattern What is a State? A State, models how a system responds to events for a particular point in time.
55. The Pattern
56. The Pattern Apply to our Invoices
57. Diagram Invoice fl ow using a State Diagram The Pattern Apply to our Invoices
58. Events States The Pattern Apply to our Invoices
59. The Pattern Apply to our Invoices States Events • Finalize • Pay • Cancel • Void • Draft • Open • Paid • Void • Uncollectable
60. State Diagram The Pattern
61. State Diagram The Pattern
62. State Diagram The Pattern
63. State Diagram The Pattern
64. State Diagram The Pattern
65. State Diagram The Pattern
66. State Diagram The Pattern
67. State Diagram The Pattern
68. State Diagram The Pattern
69. State Diagram The Pattern
70. State Diagram The Pattern
71. State Diagram The Pattern
72. State Diagram The Pattern
73. State Diagram The Pattern
74. State Diagram The Pattern
75. State Diagram The Pattern
76. State Diagram The Pattern
77. The Pattern
78. The Implementation
81. The Implementation
82. Tracking State The Implementation
83. The Implementation class Invoice
84. The Implementation class Invoice extends Model { protected $attributes = [ 'status' => 'draft', ]; }
85. State Diagram The Implementation
86. State = Class The Implementation
87. State = Class The Implementation
88. Event = Method The Implementation
89. Event = Method The Implementation
90. Event = Method The Implementation interface InvoiceStateContract { function finalize(); function pay(); function void(); function cancel(); }
91. Event = Method The Implementation class DraftInvoiceState implements InvoiceStateContract { function finalize() {} function pay() {} function void() {} function cancel() {} }
92. Event = Method The Implementation
93. Event = Method The Implementation
94. Event = Method The Implementation class DraftInvoiceState implements InvoiceStateContract { function finalize() {} function pay() {} function void() {} function cancel() {} }
95. Event = Method The Implementation class DraftInvoiceState implements InvoiceStateContract { function finalize() { $this->invoice->update(['status' => ‘open']); } function pay() {} function void() {} function cancel() {} }
96. Event = Method The Implementation class DraftInvoiceState implements InvoiceStateContract { function finalize() { $this->invoice->update(['status' => ‘open']); Mail::send(new InvoiceDue($invoice)); } function pay() {} function void() {} function cancel() {} }
97. Event = Method The Implementation
98. Event = Method The Implementation class DraftInvoiceState implements InvoiceStateContract { function finalize() { $this->invoice->update(['status' => ‘open']); Mail::send(new InvoiceDue($this->invoice)); } function pay() {} function void() {} function cancel() {} }
99. Event = Method The Implementation class DraftInvoiceState implements InvoiceStateContract { function finalize() { $this->invoice->update(['status' => ‘open']); Mail::send(new InvoiceDue($this->invoice)); } function pay() { throw new Exception(); } function void() { throw new Exception(); } function cancel() { throw new Exception(); } }
100. Event = Method The Implementation
101. Event = Method The Implementation
102. Event = Method The Implementation class OpenInvoiceState implements InvoiceStateContract { function finalize() {} function pay() {} function void() {} function cancel() {} }
103. Event = Method The Implementation
104. Event = Method The Implementation class OpenInvoiceState implements InvoiceStateContract { function finalize() {} function pay() {} function void() {} function cancel() {} }
105. Event = Method The Implementation class OpenInvoiceState implements InvoiceStateContract { function finalize() { throw new Exception(); } function pay() {} function void() {} function cancel() {} }
106. Event = Method The Implementation
107. Event = Method The Implementation class OpenInvoiceState implements InvoiceStateContract { function finalize() { throw new Exception(); } function pay() {} function void() {} function cancel() {} }
108. class OpenInvoiceState implements InvoiceStateContract { function finalize() { throw new Exception(); } function pay() { $this->invoice->update(['status' => 'paid']); } function void() { $this->invoice->update(['status' => 'void']); } Event = Method The Implementation
109. { function finalize() { throw new Exception(); } function pay() { $this->invoice->update(['status' => ‘paid']); Mail::send(new InvoicePaid($this->invoice)); } function void() { $this->invoice->update(['status' => 'void']); } function cancel() { $this->invoice->update(['status' => 'uncollectable']); } Event = Method The Implementation
110. Event = Method The Implementation
111. Event = Method The Implementation
112. Event = Method The Implementation class UncollectableInvoiceState implements InvoiceStateContract { function finalize() {} function pay() {} function void() {} function cancel() {} }
113. Event = Method The Implementation class UncollectableInvoiceState implements InvoiceStateContract { function finalize() { throw new Exception(); } function pay() {} function void() {} function cancel() { throw new Exception(); } }
114. Event = Method The Implementation
115. Event = Method The Implementation
116. Event = Method The Implementation class UncollectableInvoiceState implements InvoiceStateContract { function finalize() { throw new Exception(); } function pay() {} function void() {} function cancel() { throw new Exception(); } }
117. Event = Method The Implementation class UncollectableInvoiceState implements InvoiceStateContract { function finalize() { throw new Exception(); } function pay() { $this->invoice->update(['status' => 'paid']); } function void() { $this->invoice->update(['status' => 'void']); }
118. Event = Method The Implementation class UncollectableInvoiceState implements InvoiceStateContract { function finalize() { throw new Exception(); } function pay() { $this->invoice->update(['status' => ‘paid']); Mail::send(new CancelledInvoicePaid($this->invoice)); } function void() { $this->invoice->update(['status' => 'void']); }
119. Event = Method The Implementation
120. Event = Method The Implementation
121. Event = Method The Implementation class PaidInvoiceState implements InvoiceStateContract { function finalize() {} function pay() {} function void() {} function cancel() {} } class VoidInvoiceState implements InvoiceStateContract { function finalize() {} function pay() {} function void() {} function cancel() {} }
122. Event = Method The Implementation class PaidInvoiceState implements InvoiceStateContract { function finalize() { throw new Exception(); } function pay() { throw new Exception(); } function void() { throw new Exception(); } function cancel() { throw new Exception(); } } class VoidInvoiceState implements InvoiceStateContract { function finalize() { throw new Exception(); } function pay() { throw new Exception(); } function void() { throw new Exception(); } function cancel() { throw new Exception(); } }
123. The Implementation
124. The Implementation Cleaning up
125. Cleaning Up The Implementation class BaseInvoiceState { }
126. Cleaning Up The Implementation class BaseInvoiceState { function __construct(public Invoice $invoice) {} }
127. Cleaning Up The Implementation class BaseInvoiceState implements InvoiceStateContract { function __construct(public Invoice $invoice) {} }
128. Cleaning Up The Implementation class BaseInvoiceState implements InvoiceStateContract { function __construct(public Invoice $invoice) {} function finalize() {} function pay() {} function void() {} function cancel() {} }
129. Cleaning Up The Implementation class BaseInvoiceState implements InvoiceStateContract { function __construct(public Invoice $invoice) {} function finalize() { throw new Exception(); } function pay() { throw new Exception(); } function void() { throw new Exception(); } function cancel() { throw new Exception(); } }
130. Cleaning Up The Implementation class DraftInvoiceState implements InvoiceStateContract { function finalize() { $this->invoice->update(['status' => 'open']); Mail::send(new InvoiceDue($this->invoice)); } function pay() { throw new Exception(); } function void() { throw new Exception(); } function cancel() { throw new Exception(); } }
131. Cleaning Up The Implementation class DraftInvoiceState implements InvoiceStateContract { function finalize() { $this->invoice->update(['status' => 'open']); Mail::send(new InvoiceDue($this->invoice)); } function pay() { throw new Exception(); } function void() { throw new Exception(); } function cancel() { throw new Exception(); } }
132. Cleaning Up The Implementation class DraftInvoiceState extends BaseInvoiceState { function finalize() { $this->invoice->update(['status' => 'open']); Mail::send(new InvoiceDue($this->invoice)); } function pay() { throw new Exception(); } function void() { throw new Exception(); } function cancel() { throw new Exception(); } }
133. Cleaning Up The Implementation class DraftInvoiceState extends BaseInvoiceState { function finalize() { $this->invoice->update(['status' => 'open']); Mail::send(new InvoiceDue($this->invoice)); } function pay() { throw new Exception(); } function void() { throw new Exception(); } function cancel() { throw new Exception(); } }
134. Cleaning Up The Implementation class DraftInvoiceState extends BaseInvoiceState { function finalize() { $this->invoice->update(['status' => 'open']); Mail::send(new InvoiceDue($this->invoice)); } }
135. The Implementation Cleaning up
136. The Implementation Model State Machine
137. class Invoice extends Model The Implementation Model State Machine
138. Model State Machine The Implementation class Invoice extends Model { protected $attributes = [ 'status' => 'draft', ]; }
139. Model State Machine The Implementation class Invoice extends Model { protected $attributes = [ 'status' => 'draft', ]; public function state(): InvoiceStateContract { } }
140. Model State Machine The Implementation public function state(): InvoiceStateContract { }
141. Model State Machine The Implementation public function state(): InvoiceStateContract { } return match ($this->status) { 'draft' => new DraftInvoiceState($this), 'open' => new OpenInvoiceState($this), 'paid' => new PaidInvoiceState($this), 'void' => new VoidInvoiceState($this), 'uncollectable' => new UncollectableInvoiceState($this), default => throw new InvalidArgumentException('Invalid status'), };
142. The Implementation Model State Machine $invoice->state()
143. The Implementation Model State Machine
144. The Implementation Usage
145. Usage The Implementation
146. class FinalizeInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { if (filled($invoice->finalized_at) || filled($invoice->paid_at) || filled($invoice->void_at) || filled($invoice->cancelled_at) ) { abort(403, 'Invoice cannot be finalized'); } $invoice->update(['finalized_at' => now()]); Mail::send(new InvoiceDue($invoice)); return view('invoice.show', ['invoice' => $invoice]); } }
147. class FinalizeInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { if (filled($invoice->finalized_at) || filled($invoice->paid_at) || filled($invoice->void_at) || filled($invoice->cancelled_at) ) { abort(403, 'Invoice cannot be finalized'); } $invoice->update(['finalized_at' => now()]); Mail::send(new InvoiceDue($invoice)); return view('invoice.show', ['invoice' => $invoice]); } }
148. class FinalizeInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { if (filled($invoice->finalized_at) || filled($invoice->paid_at) || filled($invoice->void_at) || filled($invoice->cancelled_at) ) { abort(403, 'Invoice cannot be finalized'); } $invoice->update(['finalized_at' => now()]); Mail::send(new InvoiceDue($invoice)); return view('invoice.show', ['invoice' => $invoice]); } }
149. class FinalizeInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { if (filled($invoice->finalized_at) || filled($invoice->paid_at) || filled($invoice->void_at) || filled($invoice->cancelled_at) ) { abort(403, 'Invoice cannot be finalized'); } $invoice->update(['finalized_at' => now()]); Mail::send(new InvoiceDue($invoice)); return view('invoice.show', ['invoice' => $invoice]); } }
150. Usage The Implementation class FinalizeInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { $invoice->state()->finalize(); return view('invoice.show', ['invoice' => $invoice]); } }
151. Usage The Implementation class FinalizeInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { $invoice->state()->finalize(); return view('invoice.show', ['invoice' => $invoice]); } }
152. class PayInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { if ( blank($invoice->finalized_at) || filled($invoice->paid_at) || filled($invoice->uncollectable_at) || filled($invoice->void_at) ) { abort(403, 'Invoice cannot be paid'); } $invoice->update(['paid_at' => now()]); Mail::send(new InvoicePaid($invoice)); return view('invoice.thanks', ['invoice' => $invoice]); } }
153. class PayInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { if ( blank($invoice->finalized_at) || filled($invoice->paid_at) || filled($invoice->uncollectable_at) || filled($invoice->void_at) ) { abort(403, 'Invoice cannot be paid'); } $invoice->update(['paid_at' => now()]); Mail::send(new InvoicePaid($invoice)); return view('invoice.thanks', ['invoice' => $invoice]); } }
154. class PayInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { $invoice->state()->pay(); return view('invoice.thanks', ['invoice' => $invoice]); } }
155. Event = Method The Implementation
156. class PayInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { $invoice->state()->pay(); return view('invoice.thanks', ['invoice' => $invoice]); } }
157. class OpenInvoiceState implements InvoiceStateContract { function pay() { $this->invoice->update(['status' => ‘paid']); Mail::send(new InvoicePaid($this->invoice)); } }
158. class OpenInvoiceState implements InvoiceStateContract { function pay() { $this->invoice->update(['status' => ‘paid']); Mail::send(new InvoicePaid($this->invoice)); } }
159. class OpenInvoiceState implements InvoiceStateContract { function pay() { $this->invoice->update(['status' => ‘paid']); Mail::send(new InvoicePaid($this->invoice)); } }
160. class UncollectableInvoiceState implements InvoiceStateContract { function pay() { $this->invoice->update(['status' => ‘paid']); Mail::send(new CancelledInvoicePaid($this->invoice)); } } class OpenInvoiceState implements InvoiceStateContract { function pay() { $this->invoice->update(['status' => ‘paid']); Mail::send(new InvoicePaid($this->invoice)); } }
161. class UncollectableInvoiceState implements InvoiceStateContract { function pay() { $this->invoice->update(['status' => ‘paid']); Mail::send(new CancelledInvoicePaid($this->invoice)); } } class OpenInvoiceState implements InvoiceStateContract { function pay() { $this->invoice->update(['status' => ‘paid']); Mail::send(new InvoicePaid($this->invoice)); } }
162. class PayInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { $invoice->state()->pay(); return view('invoice.thanks', ['invoice' => $invoice]); } }
163. class PayInvoiceController extends Controller { public function __invoke(Request $request, Invoice $invoice) { $invoice->state()->pay(); return view('invoice.thanks', ['invoice' => $invoice]); } }
164. The Implementation Event-Action
165. The Implementation Event-State-Action
166. Benefits The Implementation
167. • Di ffi cult to determine what rules apply when • Duplication of logic every place we want to update Invoice • Code only ever grows in complexity The Implementation Benefits
168. • Di ffi cult to determine what rules apply when • Duplication of logic every place we want to update Invoice • Code only ever grows in complexity The Implementation Benefits
169. • Di ffi cult to determine what rules apply when • Duplication of logic every place we want to update Invoice • Code only ever grows in complexity The Implementation Benefits
170. • Di ffi cult to determine what rules apply when • Duplication of logic every place we want to update Invoice • Code only ever grows in complexity The Implementation Benefits
171. State Machines
178. Jake Bennett jacobbennett