Merge branch 'cor-pattern'

ChainOfResponsibilities/ChainOfResponsibilities.php

@@ -10,6 +10,8 @@ namespace DesignPatterns;
  * in the chain and so forth
  *
  * Examples:
+ * - logging framework
+ * - spam filter
  * - Caching: first object is an instance of e.g. a Memcached Interface, if that "misses" it delegates the call to the
  *   Database Interface
  * - Yii Framework: CFilterChain is a chain of controller action filters. the executing point is passed from one filter
@@ -17,6 +19,8 @@ namespace DesignPatterns;
  *
  */
 
+// the idea is good but in general, the Handler component in this pattern 
+// is an abstract class which makes much more of the work
 interface KeyValueStorage
 {
     public function get($key);

ChainOfResponsibilities/Handler.php

@@ -0,0 +1,72 @@
+<?php
+
+/*
+ * DesignPatternPHP
+ */
+
+namespace DesignPatterns\ChainOfResponsibilities;
+
+/**
+ * Handler is a generic handler in the chain of responsibilities
+ * 
+ * Yes you could have a lighter CoR with simpler handler but if you want your CoR to
+ * be extendable and decoupled, it's a better idea to do things like that in real
+ * situations. Usually, a CoR is meant to be changed everytime and evolves, that's
+ * why we slice the workflow in little bits of code.
+ */
+abstract class Handler
+{
+
+    private $successor = null;
+
+    /**
+     * Append a responsibility to the end of chain
+     * 
+     * A prepend method could be done with the same spirit
+     * 
+     * You could also send the successor in the contructor but in PHP it is a
+     * bad idea because you have to remove the type-hint of the parameter because
+     * the last handler has a null successor.
+     * 
+     * And if you override the contructor, that Handler can no longer have a
+     * successor. One solution is to provide a NullObject (see pattern).
+     * It is more preferable to keep the constructor "free" to inject services
+     * you need with the DiC of symfony2 for example.
+     */
+    final public function append(Handler $handler)
+    {
+        if (is_null($this->successor)) {
+            $this->successor = $handler;
+        } else {
+            $this->successor->append($handler);
+        }
+    }
+
+    /**
+     * Handle the request. 
+     * 
+     * This approach by using a template method pattern ensures you that 
+     * each subclass will not forget to call the successor. Beside, the returned
+     * boolean value indicates you if the request have been processed or not.
+     */
+    final public function handle(Request $req)
+    {
+        $req->forDebugOnly = get_called_class();
+        $processed = $this->processing($req);
+        if (!$processed) {
+            // the request has not been processed by this handler => see the next
+            if (!is_null($this->successor)) {
+                $processed = $this->successor->handle($req);
+            }
+        }
+
+        return $processed;
+    }
+
+    /**
+     * Each concrete handler has to implement the processing of the request
+     * 
+     * @return bool true if the request has been processed
+     */
+    abstract protected function processing(Request $req);
+}

ChainOfResponsibilities/Request.php

@@ -0,0 +1,23 @@
+<?php
+
+/*
+ * DesignPatternPHP
+ */
+
+namespace DesignPatterns\ChainOfResponsibilities;
+
+/**
+ * Request is a request which goes throught the chain of responsibilities.
+ * 
+ * About the request : Sometimes, you don't need an object, just an integer or
+ * an array. But in this case of a full example, I've made a class to illustrate 
+ * this important idea in the CoR (Chain of Responsibilities). In real world,
+ * I recommand to always use a class, even a \stdClass if you want, it proves
+ * to be more adaptative because a single handler doesn't know much about the
+ * outside world and it is more difficult if, one day, you want add some 
+ * criterion in a decision process. 
+ */
+class Request
+{
+    // getter and setter but I don't want to generate to much noise in handlers
+}

ChainOfResponsibilities/Responsible/FastStorage.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * DesignPatternPHP
+ */
+
+namespace DesignPatterns\ChainOfResponsibilities\Responsible;
+
+use DesignPatterns\ChainOfResponsibilities\Handler;
+use DesignPatterns\ChainOfResponsibilities\Request;
+
+class FastStorage extends Handler
+{
+
+    protected $_data = array();
+
+    public function __construct($data = array())
+    {
+        $this->_data = $data;
+    }
+
+    protected function processing(Request $req)
+    {
+        if ('get' === $req->verb) {
+            if (array_key_exists($req->key, $this->_data)) {
+                // the handler IS responsible and then processes the request
+                $req->response = $this->_data[$req->key];
+                // instead of returning true, I could return the value but it proves
+                // to be a bad idea. What if the value IS "false" ?
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+}

ChainOfResponsibilities/Responsible/SlowStorage.php

@@ -0,0 +1,44 @@
+<?php
+
+/*
+ * DesignPatternPHP
+ */
+
+namespace DesignPatterns\ChainOfResponsibilities\Responsible;
+
+use DesignPatterns\ChainOfResponsibilities\Handler;
+use DesignPatterns\ChainOfResponsibilities\Request;
+
+/**
+ * This is mostly the same code as FastStorage but in fact, it may greatly differs
+ * 
+ * One important fact about CoR : each item in the chain MUST NOT assume its position
+ * in the chain. A CoR is not responsible if the request is not handled UNLESS
+ * you make an "ExceptionHandler" which throws execption if the request goes there.
+ * 
+ * To be really extendable, each handler doesn't know if there is something after him.
+ * 
+ */
+class SlowStorage extends Handler
+{
+
+    protected $_data = array();
+
+    public function __construct($data = array())
+    {
+        $this->_data = $data;
+    }
+
+    protected function processing(Request $req)
+    {
+        if ('get' === $req->verb) {
+            if (array_key_exists($req->key, $this->_data)) {
+                $req->response = $this->_data[$req->key];
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+}

Tests/ChainOfResponsibilities/ChainTest.php

@@ -0,0 +1,78 @@
+<?php
+
+/*
+ * DesignPatternPHP
+ */
+
+namespace DesignPatterns\Tests\ChainOfResponsibilities;
+
+use DesignPatterns\ChainOfResponsibilities\Request;
+use DesignPatterns\ChainOfResponsibilities\Responsible;
+
+/**
+ * ChainTest tests the CoR
+ */
+class ChainTest extends \PHPUnit_Framework_TestCase
+{
+
+    protected $chain;
+
+    protected function setUp()
+    {
+        $this->chain = new Responsible\FastStorage(array('bar' => 'baz'));
+        $this->chain->append(new Responsible\SlowStorage(array('bar' => 'baz', 'foo' => 'bar')));
+    }
+
+    public function makeRequest()
+    {
+        $request = new Request();
+        $request->verb = 'get';
+        return array(
+            array($request)
+        );
+    }
+
+    /**
+     * @dataProvider makeRequest
+     */
+    public function testFastStorage($request)
+    {
+        $request->key = 'bar';
+        $ret = $this->chain->handle($request);
+
+        $this->assertTrue($ret);
+        $this->assertObjectHasAttribute('response', $request);
+        $this->assertEquals('baz', $request->response);
+        // despite both handle owns the 'bar' key, the FastStorage is responding first
+        $this->assertEquals('DesignPatterns\ChainOfResponsibilities\Responsible\FastStorage', $request->forDebugOnly);
+    }
+
+    /**
+     * @dataProvider makeRequest
+     */
+    public function testSlowStorage($request)
+    {
+        $request->key = 'foo';
+        $ret = $this->chain->handle($request);
+
+        $this->assertTrue($ret);
+        $this->assertObjectHasAttribute('response', $request);
+        $this->assertEquals('bar', $request->response);
+        // FastStorage has no 'foo' key, the SlowStorage is responding
+        $this->assertEquals('DesignPatterns\ChainOfResponsibilities\Responsible\SlowStorage', $request->forDebugOnly);
+    }
+
+    /**
+     * @dataProvider makeRequest
+     */
+    public function testFailure($request)
+    {
+        $request->key = 'kurukuku';
+        $ret = $this->chain->handle($request);
+
+        $this->assertFalse($ret);
+        // the last rsponsible :
+        $this->assertEquals('DesignPatterns\ChainOfResponsibilities\Responsible\SlowStorage', $request->forDebugOnly);
+    }
+
+}