Feature/Allow to set custom StateChanged event

docs/working-with-states/01-configuring-states.md

@@ -111,6 +111,27 @@ abstract class PaymentState extends State
 }
 ```
 
+### Registering custom StateChanged event
+By default, when a state is changed, the `StateChanged` event is fired. If you want to use a custom event, you can register it in the `config` method:
+
+```php
+use Spatie\ModelStates\State;
+use Spatie\ModelStates\StateConfig;
+
+use Your\Concrete\State\Event\CustomStateChanged;
+
+abstract class PaymentState extends State
+{
+    abstract public function color(): string;
+
+    public static function config(): StateConfig
+    {
+        return parent::config()
+            ->stateChangedEvent(CustomStateChanged::class)
+        ;
+    }
+}
+```
 ## Configuring states using attributes
 
 If you're using PHP 8 or higher, you can also configure your state using attributes:

src/State.php

@@ -8,6 +8,7 @@
 use ReflectionClass;
 use Spatie\ModelStates\Attributes\AttributeLoader;
 use Spatie\ModelStates\Events\StateChanged;
+use Spatie\ModelStates\Exceptions\ClassDoesNotExtendBaseClass;
 use Spatie\ModelStates\Exceptions\CouldNotPerformTransition;
 use Spatie\ModelStates\Exceptions\InvalidConfig;
 
@@ -169,8 +170,9 @@ public function transitionTo($newState, ...$transitionArgs)
     }
 
     /**
-     * @param  Transition  $transition
+     * @param Transition $transition
      * @return  \Illuminate\Database\Eloquent\Model
+     * @throws ClassDoesNotExtendBaseClass
      */
     public function transition(Transition $transition)
     {
@@ -183,7 +185,13 @@ public function transition(Transition $transition)
         $model = app()->call([$transition, 'handle']);
         $model->{$this->field}->setField($this->field);
 
-        event(new StateChanged(
+        $stateChangedEvent = $this->stateConfig->stateChangedEvent;
+
+        if ($stateChangedEvent !== StateChanged::class && get_parent_class($stateChangedEvent) !== StateChanged::class) {
+            throw ClassDoesNotExtendBaseClass::make($stateChangedEvent, StateChanged::class);
+        }
+
+        event(new $stateChangedEvent(
             $this,
             $model->{$this->field},
             $transition,

src/StateConfig.php

@@ -2,6 +2,7 @@
 
 namespace Spatie\ModelStates;
 
+use Spatie\ModelStates\Events\StateChanged;
 use Spatie\ModelStates\Exceptions\InvalidConfig;
 
 class StateConfig
@@ -18,6 +19,8 @@ class StateConfig
     /** @var string[] */
     public array $registeredStates = [];
 
+    public string $stateChangedEvent = StateChanged::class;
+
     public function __construct(
         string $baseStateClass
     ) {
@@ -117,6 +120,13 @@ public function registerState($stateClass): StateConfig
         return $this;
     }
 
+    public function stateChangedEvent(string $event): StateConfig
+    {
+        $this->stateChangedEvent = $event;
+
+        return $this;
+    }
+
     /**
      * @param string|\Spatie\ModelStates\State $from
      * @param string|\Spatie\ModelStates\State $to

tests/Dummy/CustomEventModelState/CustomEventModelState.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Spatie\ModelStates\Tests\Dummy\CustomEventModelState;
+
+use Spatie\ModelStates\State;
+use Spatie\ModelStates\StateConfig;
+
+abstract class CustomEventModelState extends State
+{
+    public static function config(): StateConfig
+    {
+        return parent::config()
+            ->default(CustomEventModelStateA::class)
+            ->allowTransition(CustomEventModelStateA::class, CustomEventModelStateB::class)
+            ->stateChangedEvent(CustomStateChangedEvent::class);
+    }
+}

tests/Dummy/CustomEventModelState/CustomEventModelStateA.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Spatie\ModelStates\Tests\Dummy\CustomEventModelState;
+
+class CustomEventModelStateA extends CustomEventModelState
+{
+
+}

tests/Dummy/CustomEventModelState/CustomEventModelStateB.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Spatie\ModelStates\Tests\Dummy\CustomEventModelState;
+
+class CustomEventModelStateB extends CustomEventModelState
+{
+
+}

tests/Dummy/CustomEventModelState/CustomInvalidEventModelState.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Spatie\ModelStates\Tests\Dummy\CustomEventModelState;
+
+use Spatie\ModelStates\State;
+use Spatie\ModelStates\StateConfig;
+
+abstract class CustomInvalidEventModelState extends State
+{
+    public static function config(): StateConfig
+    {
+        return parent::config()
+            ->default(CustomInvalidEventModelStateA::class)
+            ->allowTransition(CustomInvalidEventModelStateA::class, CustomInvalidEventModelStateB::class)
+            ->stateChangedEvent(CustomInvalidStateChangedEvent::class);
+    }
+}

tests/Dummy/CustomEventModelState/CustomInvalidEventModelStateA.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Spatie\ModelStates\Tests\Dummy\CustomEventModelState;
+
+class CustomInvalidEventModelStateA extends CustomInvalidEventModelState
+{
+
+}

tests/Dummy/CustomEventModelState/CustomInvalidEventModelStateB.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Spatie\ModelStates\Tests\Dummy\CustomEventModelState;
+
+class CustomInvalidEventModelStateB extends CustomInvalidEventModelState
+{
+
+}

tests/Dummy/CustomEventModelState/CustomInvalidStateChangedEvent.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Spatie\ModelStates\Tests\Dummy\CustomEventModelState;
+
+use Spatie\ModelStates\Events\StateChanged;
+use Spatie\ModelStates\State;
+use Spatie\ModelStates\Transition;
+
+class CustomInvalidStateChangedEvent
+{
+
+}

tests/Dummy/CustomEventModelState/CustomStateChangedEvent.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Spatie\ModelStates\Tests\Dummy\CustomEventModelState;
+
+use Spatie\ModelStates\Events\StateChanged;
+use Spatie\ModelStates\State;
+use Spatie\ModelStates\Transition;
+
+class CustomStateChangedEvent extends StateChanged
+{
+
+}

tests/Dummy/TestModelCustomEvent.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Spatie\ModelStates\Tests\Dummy;
+
+use Illuminate\Database\Eloquent\Model;
+use Spatie\ModelStates\HasStates;
+use Spatie\ModelStates\Tests\Dummy\CustomEventModelState\CustomEventModelState;
+use Spatie\ModelStates\Tests\Dummy\ModelStates\ModelState;
+
+class TestModelCustomEvent extends TestModel
+{
+    protected $casts = [
+        'state' => CustomEventModelState::class,
+    ];
+}

tests/Dummy/TestModelCustomInvalidEvent.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Spatie\ModelStates\Tests\Dummy;
+
+use Illuminate\Database\Eloquent\Model;
+use Spatie\ModelStates\HasStates;
+use Spatie\ModelStates\Tests\Dummy\CustomEventModelState\CustomEventModelState;
+use Spatie\ModelStates\Tests\Dummy\CustomEventModelState\CustomInvalidEventModelState;
+use Spatie\ModelStates\Tests\Dummy\ModelStates\ModelState;
+
+class TestModelCustomInvalidEvent extends TestModel
+{
+    protected $casts = [
+        'state' => CustomInvalidEventModelState::class,
+    ];
+}

tests/StateTest.php

@@ -1,6 +1,12 @@
 <?php
 
 use Illuminate\Support\Facades\Event;
+use Spatie\ModelStates\Events\StateChanged;
+use Spatie\ModelStates\Exceptions\ClassDoesNotExtendBaseClass;
+use Spatie\ModelStates\Tests\Dummy\CustomEventModelState\CustomEventModelStateB;
+use Spatie\ModelStates\Tests\Dummy\CustomEventModelState\CustomInvalidEventModelStateB;
+use Spatie\ModelStates\Tests\Dummy\CustomEventModelState\CustomInvalidStateChangedEvent;
+use Spatie\ModelStates\Tests\Dummy\CustomEventModelState\CustomStateChangedEvent;
 use Spatie\ModelStates\Tests\Dummy\ModelStates\ModelState;
 use Spatie\ModelStates\Tests\Dummy\ModelStates\StateA;
 use Spatie\ModelStates\Tests\Dummy\ModelStates\StateB;
@@ -13,6 +19,8 @@
 use Spatie\ModelStates\Tests\Dummy\OtherModelStates\StateX;
 use Spatie\ModelStates\Tests\Dummy\OtherModelStates\StateY;
 use Spatie\ModelStates\Tests\Dummy\TestModel;
+use Spatie\ModelStates\Tests\Dummy\TestModelCustomEvent;
+use Spatie\ModelStates\Tests\Dummy\TestModelCustomInvalidEvent;
 use Spatie\ModelStates\Tests\Dummy\TestModelUpdatingEvent;
 use Spatie\ModelStates\Tests\Dummy\TestModelWithCustomTransition;
 use Spatie\ModelStates\Tests\Dummy\TestModelWithDefault;
@@ -208,3 +216,34 @@
 
     Event::assertNotDispatched(TestModelUpdatingEvent::class);
 });
+
+it('can emit a custom state changed event', function () {
+    Event::fake();
+
+    $model = TestModelCustomEvent::create();
+
+    $model->state->transitionTo(CustomEventModelStateB::class);
+
+    Event::assertDispatched(CustomStateChangedEvent::class);
+});
+
+it('emits the standard state changed event', function () {
+    Event::fake();
+
+    $model = TestModel::create();
+
+    $model->state->transitionTo(StateB::class);
+
+    Event::assertDispatched(StateChanged::class);
+});
+
+it('should throw exception when custom state changed event does not extend StateChanged', function () {
+    Event::fake();
+
+    $model = TestModelCustomInvalidEvent::create();
+
+    $this->expectException(ClassDoesNotExtendBaseClass::class);
+    $this->expectExceptionMessage('Class ' . CustomInvalidStateChangedEvent::class . ' does not extend the `' . StateChanged::class . '` base class.');
+
+    $model->state->transitionTo(CustomInvalidEventModelStateB::class);
+});