wip

README.md

@@ -17,15 +17,16 @@ composer require hemp/machinery
 
 ## Usage
 
-First, create an enumeration that represents the states for your Eloquent model and the valid transitions between them:
+First, create an enumeration that represents the states you wish to 
+model and the valid transitions between them:
 
 ```php
-use Hemp\Machinery\MachineState;
-use Hemp\Machinery\MachineStateTrait;
+use Hemp\Machinery\MachineryState;
+use Hemp\Machinery\MachineryEnumeration;
 
-enum OrderStatus: string implements MachineState
+enum OrderStatus: string implements MachineryState
 {
-    use MachineStateTrait;
+    use MachineryEnumeration;
 
     case Processing : 'processing';
     case Shipped : 'shipped';
@@ -48,6 +49,24 @@ enum OrderStatus: string implements MachineState
 }
 ```
 
+Now you can use the `OrderStatus` enumeration to manage transitions 
+between states:
+
+```php
+use Hemp\Machinery\Machinery;
+
+OrderStatus::Processing->canTransitionTo(OrderStatus::Shipped); // true
+OrderStatus::Processing->transitionTo(OrderStatus::Shipped); // state is now 'shipped'
+
+OrderStatus::Shipped->canTransitionTo(OrderStatus::Delivered); // true
+OrderStatus::Shipped->transitionTo(OrderStatus::Delivered); // state is now 'delivered'
+
+OrderStatus::Delivered->canTransitionTo(OrderStatus::Processing); // 
+OrderStatus::Delivered->transitionTo(OrderStatus::Processing); // Throws an exception...
+```
+
+## Using the state machine with Eloquent
+
 Next, add a column to your Eloquent model's `casts` to store the state:
 
 ```php

src/Machinery.php

@@ -4,7 +4,7 @@
 
 trait Machinery
 {
-    public function transitionTo($machineKey, MachineState $state, ?callable $sideEffect = null): MachineState
+    public function transitionTo($machineKey, MachineryState $state, ?callable $sideEffect = null): MachineryState
     {
         $sideEffect = $sideEffect ?? fn () => null;
 
@@ -16,7 +16,7 @@ public function transitionTo($machineKey, MachineState $state, ?callable $sideEf
         return $this->{$machineKey}->transitionTo($state, $callable);
     }
 
-    public function canTransitionTo($machineKey, MachineState $state): bool
+    public function canTransitionTo($machineKey, MachineryState $state): bool
     {
         return $this->{$machineKey}->canTransitionTo($state);
     }

src/MachineStateTrait.php → src/MachineryEnumeration.php

@@ -5,30 +5,29 @@
 /**
  * @method static transitions()
  */
-trait MachineStateTrait
+trait MachineryEnumeration
 {
     /**
      * @throws InvalidStateTransition
      */
-    public function transitionTo(MachineState $state, ?callable $sideEffect = null): MachineState
+    public function transitionTo(MachineryState $state, ?callable $sideEffect = null): MachineryState
     {
-        $callback = $sideEffect ?? fn () => null;
 
-        if (! $this->canTransitionTo($state)) {
+        if (!$this->canTransitionTo($state)) {
             throw new InvalidStateTransition("Cannot transition from state [{$this->value}] to state [{$state->value}].");
         }
 
-        $callback();
+        call_user_func($sideEffect ?? fn() => null);
 
         return $state;
     }
 
-    public function canTransitionTo(MachineState $state): bool
+    public function canTransitionTo(MachineryState $state): bool
     {
         return in_array($state, self::transitions()[$this->value]);
     }
 
-    public function is(MachineState $state): bool
+    public function is(MachineryState $state): bool
     {
         return $this->value === $state->value;
     }

src/MachineryState.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Hemp\Machinery;
+
+interface MachineryState
+{
+    public function transitionTo(MachineryState $state, callable $sideEffect): MachineryState;
+
+    public static function transitions(): array;
+
+    public function canTransitionTo(MachineryState $state): bool;
+}

tests/Fixtures/Status.php

@@ -2,12 +2,12 @@
 
 namespace Hemp\Machinery\Tests\Fixtures;
 
-use Hemp\Machinery\MachineState;
-use Hemp\Machinery\MachineStateTrait;
+use Hemp\Machinery\MachineryState;
+use Hemp\Machinery\MachineryEnumeration;
 
-enum Status: string implements MachineState
+enum Status: string implements MachineryState
 {
-    use MachineStateTrait;
+    use MachineryEnumeration;
 
     case Active = 'active';