decoupled transition schema

Author: coff

CHANGELOG.md

@@ -1,5 +1,22 @@
 # CHANGELOG
 
+## dev-decoupled-transition-schema
+
+- [BC break] decoupled transition `Schema` from actual state machine for easier DI of a whole schema
+- [BC break] removed `Machine::allowTransition()` and several other transition related methods from `MachineInterface` 
+  and `Machine` implementation
+- refactored Exception classes into one hierarchy with one global `SMFException`
+- [BC break] `CommonCallbackAssertion` and `DefaultCallbackAssertion` rebuilt to run-time machine object so methods
+  `setObject()` and `setTransition` are no longer valid
+- [BC break] `Transition` class now uses run-time machine object so method `assert()` got additional parameter `$machine`
+- [BC break] `Schema::addTransition()` (before `Machine::addTransition()`) now throws `ConfigurationException` instead of
+  `MachineException`
+- added `TransitionInterface::onTransition()` method
+- [BC break] `Machine::setMachineState` now throws `ConfigurationException` when `Schema` object not set
+- unit tests rewritten
+- [BC break] `Transition::assert()` doesn't throw `TransitionException` anymore, false is returned if there are no 
+  assertions defined 
+
 ## v1.0.0
 
 - `MachineTest`: more detailed tests implemented 

README.md

@@ -2,7 +2,7 @@
 
 Maybe state machines are not what you usually do with PHP but when you do... just use this.
 This simple yet powerful framework will keep your state machines within their desired state 
-transition cycles. You can also modify their behavior whilst running or just configure them 
+transition schemas. You can also modify their behavior whilst running or just configure them 
 dynamically and launch. You can define state transition conditions you want based upon 
 anonymous functions or class methods. Fire events on each state transition with your favorite
 event dispatcher.
@@ -60,23 +60,6 @@ For clarity each state machine should have its own state dictionary defined.
     class Petition extends Machine {
 
         protected $votesYes, $votesNo;
-    
-        public function init() {
-            $this->setInitState(PetitionEnum::DRAFT());
-            
-            // defines machine's allowed behavior
-            $this
-                // prevents changing state upon assertion when AlwaysFalseAssertion is given
-                ->allowTransition(PetitionEnum::DRAFT(), PetitionEnum::SENT(), new AlwaysFalseAssertion())
-                ->allowTransition(PetitionEnum::DRAFT(), PetitionEnum::CANCELED(), new AlwaysFalseAssertion())
-                
-                // when no Assertion is given uses DefaultCallbackAssertion which calls assertXToY methods
-                ->allowTransition(PetitionEnum::SENT(), PetitionEnum::VOTED())
-                ->allowTransition(PetitionEnum::VOTED(), PetitionEnum::ACCEPTED())
-                ->allowTransition(PetitionEnum::VOTED(), PetitionEnum::REJECTED())
-                ;
-            
-        }
 
         public function send() 
         {
@@ -124,12 +107,38 @@ For clarity each state machine should have its own state dictionary defined.
     }
 ```
 
+### Machine's transition schema definition
+
+As of version 2 transition schema is decoupled from actual machine so it can be easily injected into any machine object
+or changed when is necessary to modify machine's behavior later.
+
+```php
+
+$schema = new Schema();
+
+$schema
+    ->setInitState(PetitionEnum::DRAFT())
+    // prevents changing state upon assertion when AlwaysFalseAssertion is given
+    ->allowTransition(PetitionEnum::DRAFT(), PetitionEnum::SENT(), new AlwaysFalseAssertion())
+    ->allowTransition(PetitionEnum::DRAFT(), PetitionEnum::CANCELED(), new AlwaysFalseAssertion())
+    // when no Assertion is given uses DefaultCallbackAssertion which calls assertXToY methods
+    ->allowTransition(PetitionEnum::SENT(), PetitionEnum::VOTED())
+    ->allowTransition(PetitionEnum::VOTED(), PetitionEnum::ACCEPTED())
+    ->allowTransition(PetitionEnum::VOTED(), PetitionEnum::REJECTED());
+    
+```
+
+*Remark: By default (when no assertion object is given as parameter) `Schema::allowTransition()` method attaches `DefaultCallbackAssertion`.*
+
+
 ### Machine in-use 
 
 ```php
 
     $p = new Petition();
-    $p->init();
+    $p
+        ->setSchema($schema)
+        ->init();
 
     $p->run();
     // <nothing happens>
@@ -150,9 +159,32 @@ For clarity each state machine should have its own state dictionary defined.
 
 ### Transition object
 
-Each transition object should have one or more assertion objects attached.
+Defined as change from one state to another. Has two basic functions:
+- allows to assert if this exact transition is valid considering defined transition conditions by  them via 
+  attached assertions or conditions defined within transition class itself
+- allows to run certain code in `Transition::onTransition()` method when actual transition happens; this functionality
+  doubles that defined within machine for situations when it's required to control it externally from within transition
+  object. As well as with `Machine::onTransition()` method we can also dispatch events from here or use one common \
+  transition object for several different machines sharing some functionality. 
 
-*Remark: By default (when no assertion object is given as parameter) `Machine::allowTransition()` method attaches `DefaultCallbackAssertion`.*
+Example:
+```php
+
+    class SendToVotedTransition extends Transition {
+        public function assert(MachineInterface $machine) 
+        {
+            return $machine->hasVotes() ? true : false;    
+        }
+        
+        public function onTransition(MachineInterface $machine)
+        {
+            $machine->getPetitionStats()->incrementVotedCount();
+        }
+    } 
+
+```
+
+Each transition object should have one or more assertion objects attached.
 
 
 ### Assertion behaviors
@@ -164,7 +196,7 @@ Results in automatic transition when machine is launched.
 Be aware:
 
 ```php
-    $machine
+    $machine->getSchema()
         ->allowTransition(MachineEnum::ONE(), MachineEnum::TWO(), new AlwaysTrueAssertion)
         ->allowTransition(MachineEnum::TWO(), MachineEnum::ONE(), new AlwaysTrueAssertion)
 
@@ -179,11 +211,11 @@ changed upon `setMachineState()` method call only.
 
 #### DefaultCallbackAssertion
 
-Calls `assertXToY` method on machine object (or other object if specified) and makes transition decision upon its return.
+Calls `assertXToY` method on machine object and makes transition decision upon its return.
 
 #### CommonCallbackAssertion
 
-Calls `assertTransition` method on machine object (or other object if specified) and makes transition decision upon its return.
+Calls `assertTransition` method on machine object and makes transition decision upon its return.
 
 #### CallbackAssertion
 

example/example01.php

@@ -1,8 +1,11 @@
-<?php
+<?php /** @noinspection ALL */
 
 namespace Coff\SMF\Example;
 
 use Coff\SMF\Assertion\AlwaysFalseAssertion;
+use Coff\SMF\Schema\Schema;
+use Coff\SMF\Exception\ConfigurationException;
+use Coff\SMF\Exception\SchemaException;
 use Coff\SMF\Exception\MachineException;
 use Coff\SMF\Exception\TransitionException;
 use Coff\SMF\Machine;
@@ -36,25 +39,10 @@ class Petition extends Machine
 
     protected $votesYes, $votesNo;
 
-    public function init()
-    {
-        $this->setInitState(PetitionEnum::DRAFT());
-
-        // defines machine's allowed behavior, when no Assertion is given uses DefaultCallbackAssertion
-        $this
-            // prevents changing state upon assertion when AlwaysFalseAssertion is given
-            ->allowTransition(PetitionEnum::DRAFT(), PetitionEnum::SENT(), new AlwaysFalseAssertion())
-            ->allowTransition(PetitionEnum::DRAFT(), PetitionEnum::CANCELED(), new AlwaysFalseAssertion())
-            // when no Assertion is given uses DefaultCallbackAssertion which calls assertXToY methods
-            ->allowTransition(PetitionEnum::SENT(), PetitionEnum::VOTED())
-            ->allowTransition(PetitionEnum::VOTED(), PetitionEnum::ACCEPTED())
-            ->allowTransition(PetitionEnum::VOTED(), PetitionEnum::REJECTED());
-
-    }
-
     /**
-     * @throws MachineException
      * @throws TransitionException
+     * @throws ConfigurationException
+     * @throws SchemaException
      */
     public function send()
     {
@@ -63,7 +51,8 @@ public function send()
     }
 
     /**
-     * @throws MachineException
+     * @throws ConfigurationException
+     * @throws SchemaException
      * @throws TransitionException
      */
     public function cancel()
@@ -104,9 +93,22 @@ public function onTransition(Transition $transition)
     }
 }
 
+$Schema = new Schema();
+
+$schema
+    ->setInitState(PetitionEnum::DRAFT())
+    // prevents changing state upon assertion when AlwaysFalseAssertion is given
+    ->allowTransition(PetitionEnum::DRAFT(), PetitionEnum::SENT(), new AlwaysFalseAssertion())
+    ->allowTransition(PetitionEnum::DRAFT(), PetitionEnum::CANCELED(), new AlwaysFalseAssertion())
+    // when no Assertion is given uses DefaultCallbackAssertion which calls assertXToY methods
+    ->allowTransition(PetitionEnum::SENT(), PetitionEnum::VOTED())
+    ->allowTransition(PetitionEnum::VOTED(), PetitionEnum::ACCEPTED())
+    ->allowTransition(PetitionEnum::VOTED(), PetitionEnum::REJECTED());
 
 $p = new Petition();
-$p->init();
+$p
+    ->setSchema($schema)
+    ->init();
 
 echo 'Running...' . PHP_EOL;
 $p->run();

phpunit.xml

@@ -11,7 +11,9 @@
          syntaxCheck="false">
     <testsuites>
         <testsuite name="Application Test Suite">
-            <directory>./tests/</directory>
+            <directory>./tests/Machine</directory>
+            <directory>./tests/Schema</directory>
+            <directory>./tests/Assertion</directory>
         </testsuite>
     </testsuites>
     <filter>

src/Assertion/AlwaysFalseAssertion.php

@@ -3,12 +3,15 @@
 
 namespace Coff\SMF\Assertion;
 
+use Coff\SMF\MachineInterface;
+use Coff\SMF\Transition\TransitionInterface;
+
 /**
  * False Assertion for unit testing
  */
 class AlwaysFalseAssertion extends Assertion
 {
-    public function make(): bool
+    public function make(MachineInterface $machine, TransitionInterface $transition): bool
     {
         return false;
     }

src/Assertion/AlwaysTrueAssertion.php

@@ -4,10 +4,13 @@
 namespace Coff\SMF\Assertion;
 
 
+use Coff\SMF\MachineInterface;
+use Coff\SMF\Transition\TransitionInterface;
+
 class AlwaysTrueAssertion extends Assertion
 {
 
-    public function make(): bool
+    public function make(MachineInterface $machine, TransitionInterface $transition): bool
     {
         return true;
     }

src/Assertion/AssertionInterface.php

@@ -4,7 +4,10 @@
 namespace Coff\SMF\Assertion;
 
 
+use Coff\SMF\MachineInterface;
+use Coff\SMF\Transition\TransitionInterface;
+
 interface AssertionInterface
 {
-    public function make(): bool;
+    public function make(MachineInterface $machine, TransitionInterface $transition): bool;
 }

src/Assertion/CallbackAssertion.php

@@ -4,6 +4,8 @@
 
 
 use Coff\SMF\Exception\AssertionException;
+use Coff\SMF\MachineInterface;
+use Coff\SMF\Transition\TransitionInterface;
 
 class CallbackAssertion extends Assertion
 {
@@ -12,13 +14,13 @@ class CallbackAssertion extends Assertion
     protected $callback;
 
     /** @var array */
-    protected $params;
+    protected $extraParams = [];
 
-    public function __construct(callable $callback = null, array $params = [])
+    public function __construct(callable $callback = null, array $extra_params = [])
     {
         $this->callback = $callback;
 
-        $this->params = $params;
+        $this->extraParams = $extra_params;
     }
 
     public function setCallback(callable $callback)
@@ -28,21 +30,23 @@ public function setCallback(callable $callback)
         return $this;
     }
 
-    public function setParams($params = [])
+    public function setExtraParams($extra_params = [])
     {
-        $this->params = $params;
+        $this->extraParams = $extra_params;
 
         return $this;
     }
 
     /**
+     * @param MachineInterface $machine
+     * @param TransitionInterface $transition
      * @return bool
      * @throws AssertionException
      */
-    public function make(): bool
+    public function make(MachineInterface $machine, TransitionInterface $transition): bool
     {
         if ($this->callback) {
-            return call_user_func_array($this->callback, $this->params);
+            return call_user_func_array($this->callback, array_merge([$machine, $transition], $this->extraParams));
         } else {
             throw new AssertionException('Callback not configured!');
         }

src/Assertion/CommonCallbackAssertion.php

@@ -4,49 +4,25 @@
 namespace Coff\SMF\Assertion;
 
 
-use Coff\SMF\Exception\AssertionException;
 use Coff\SMF\MachineInterface;
 use Coff\SMF\Transition\TransitionInterface;
 
 class CommonCallbackAssertion extends CallbackAssertion
 {
-    /** @var MachineInterface $object */
-    protected $object;
-
-    /** @var TransitionInterface $transition */
-    protected $transition;
 
     public function __construct()
     {
         parent::__construct();
     }
 
-
-    public function setObject(MachineInterface $object)
-    {
-        $this->object = $object;
-
-        return $this;
-    }
-
-    public function setTransition(TransitionInterface $transition)
-    {
-        $this->transition = $transition;
-
-        return $this;
-    }
-
     /**
+     * @param MachineInterface $machine
+     * @param TransitionInterface $transition
      * @return bool
-     * @throws AssertionException
      */
-    public function make(): bool
+    public function make(MachineInterface $machine, TransitionInterface $transition): bool
     {
-        if ($this->object instanceof MachineInterface && $this->transition instanceof TransitionInterface) {
-            return call_user_func_array([$this->object, 'assertTransition'], [$this->transition]);
-        } else {
-            throw new AssertionException('Callback not configured!');
-        }
+        return call_user_func_array([$machine, 'assertTransition'], [$transition]);
     }
 
 }