State changed event

src/Events/StateChanged.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Workflow\Events;
+
+use Illuminate\Queue\SerializesModels;
+use Workflow\States\State;
+
+class StateChanged
+{
+    use SerializesModels;
+
+    public ?State $initialState;
+
+    public ?State $finalState;
+
+    public $model;
+
+    public ?string $field;
+
+    /**
+     * @param  string|State|null  $initialState
+     * @param  string|State|null  $finalState
+     * @param  \Illuminate\Database\Eloquent\Model  $model
+     */
+    public function __construct(?State $initialState, ?State $finalState, $model, string $field)
+    {
+        $this->initialState = $initialState;
+        $this->finalState = $finalState;
+        $this->model = $model;
+        $this->field = $field;
+    }
+}

src/States/State.php

@@ -9,6 +9,7 @@
 use InvalidArgumentException;
 use JsonSerializable;
 use ReflectionClass;
+use Workflow\Events\StateChanged;
 use Workflow\Exceptions\TransitionNotFound;
 
 abstract class State implements Castable, JsonSerializable
@@ -140,14 +141,21 @@ public function transitionTo($newState, ...$transitionArgs)
 
         $this->model->{$this->field} = $newState;
         $this->model->save();
-
-        $currentState = $this->model->{$this->field};
+        $model = $this->model;
+        $currentState = $model->{$this->field} ?? null;
 
         if ($currentState instanceof self) {
             $currentState->setField($this->field);
         }
 
-        return $this->model;
+        event(new StateChanged(
+            $this,
+            $currentState instanceof self ? $currentState : null,
+            $this->model,
+            $this->field
+        ));
+
+        return $model;
     }
 
     public function canTransitionTo($newState, ...$transitionArgs): bool

src/States/StateConfig.php

@@ -13,7 +13,7 @@ final class StateConfig
     public ?string $defaultStateClass = null;
 
     /**
-     * @var array<string, null|string>
+     * @var array<string, bool>
      */
     public array $allowedTransitions = [];
 
@@ -43,11 +43,11 @@ public function ignoreSameState(): self
         return $this;
     }
 
-    public function allowTransition($from, string $to, ?string $transition = null): self
+    public function allowTransition($from, string $to): self
     {
         if (is_array($from)) {
             foreach ($from as $fromState) {
-                $this->allowTransition($fromState, $to, $transition);
+                $this->allowTransition($fromState, $to);
             }
 
             return $this;
@@ -61,7 +61,7 @@ public function allowTransition($from, string $to, ?string $transition = null):
             throw new InvalidArgumentException("{$to} does not extend {$this->baseStateClass}.");
         }
 
-        $this->allowedTransitions[$this->createTransitionKey($from, $to)] = $transition;
+        $this->allowedTransitions[$this->createTransitionKey($from, $to)] = true;
 
         return $this;
     }
@@ -72,7 +72,7 @@ public function allowTransition($from, string $to, ?string $transition = null):
     public function allowTransitions(array $transitions): self
     {
         foreach ($transitions as $transition) {
-            $this->allowTransition($transition[0], $transition[1], $transition[2] ?? null);
+            $this->allowTransition($transition[0], $transition[1]);
         }
 
         return $this;

tests/Feature/StateChangedEventTest.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature;
+
+use Illuminate\Support\Facades\Event;
+use Tests\Fixtures\TestWorkflow;
+use Tests\TestCase;
+use Workflow\Events\StateChanged;
+use Workflow\Models\StoredWorkflow;
+use Workflow\States\WorkflowCreatedStatus;
+use Workflow\States\WorkflowPendingStatus;
+
+final class StateChangedEventTest extends TestCase
+{
+    public function testEventDispatchedAfterStoredWorkflowStatusTransition(): void
+    {
+        $storedWorkflow = StoredWorkflow::create([
+            'class' => TestWorkflow::class,
+        ]);
+        $storedWorkflow = StoredWorkflow::findOrFail($storedWorkflow->id);
+
+        Event::fake([StateChanged::class]);
+
+        $initialState = $storedWorkflow->status;
+        $storedWorkflow->status->transitionTo(WorkflowPendingStatus::class);
+
+        Event::assertDispatched(StateChanged::class, static function (StateChanged $event) use (
+            $storedWorkflow,
+            $initialState
+        ) {
+            return $event->initialState === $initialState
+                && $event->initialState instanceof WorkflowCreatedStatus
+                && $event->finalState instanceof WorkflowPendingStatus
+                && $event->model->is($storedWorkflow)
+                && $event->field === 'status';
+        });
+    }
+}

tests/Unit/States/StateInfrastructureTest.php

@@ -5,8 +5,10 @@
 namespace Tests\Unit\States;
 
 use Exception;
+use Illuminate\Support\Facades\Event;
 use InvalidArgumentException;
 use Tests\TestCase;
+use Workflow\Events\StateChanged;
 use Workflow\Exceptions\TransitionNotFound;
 use Workflow\States\State;
 use Workflow\States\StateCaster;
@@ -196,6 +198,8 @@ public function testStateUtilityMethods(): void
 
     public function testStateTransitionsAndEqualityChecks(): void
     {
+        Event::fake([StateChanged::class]);
+
         $model = new StateInfraModel();
         $state = new StateInfraInitialState($model);
         $state->setField('status');
@@ -213,13 +217,25 @@ public function testStateTransitionsAndEqualityChecks(): void
         $this->assertTrue($model->saved);
         $this->assertInstanceOf(StateInfraNextState::class, $model->status);
         $this->assertSame('status', $model->status->getField());
+        Event::assertDispatched(StateChanged::class, static function (StateChanged $event) use ($model, $state) {
+            return $event->initialState === $state
+                && $event->finalState instanceof StateInfraNextState
+                && $event->model === $model
+                && $event->field === 'status';
+        });
 
         $model->saved = false;
         $nextState = $model->status;
         $nextState->transitionTo(new StateInfraTerminalState($model));
 
         $this->assertTrue($model->saved);
         $this->assertInstanceOf(StateInfraTerminalState::class, $model->status);
+        Event::assertDispatched(StateChanged::class, static function (StateChanged $event) use ($model, $nextState) {
+            return $event->initialState === $nextState
+                && $event->finalState instanceof StateInfraTerminalState
+                && $event->model === $model
+                && $event->field === 'status';
+        });
 
         try {
             $model->status->transitionTo(StateInfraInitialState::class);