Merge branch 'command-more-precise-example'

Command/Command.php

@@ -1,40 +1,34 @@
 <?php
 
-namespace DesignPatterns;
+namespace DesignPatterns\Command;
 
 /**
  * Command pattern
  *
- * Purpose:
- * to build a simple interface for commands that can all be run by just executing a single method they all have in
- * common, often called 'run' or 'execute'
+ * Purpose: To encapsulate invocation and decoupling
+ * 
+ * We have an Invoker and a Receiver. This pattern use a "Command" to delegate the
+ * method call against the Receiver and use the same method "execute".
+ * Therefore, the Invoker just know to call "execute" to process the Command of
+ * the client. The Receiver is decoupled from the Invoker
+ * 
+ * The second aspect of ths pattern is the undo(), which undoes the method execute()
+ * Command can also be agregated to combine more complex commands with minimum
+ * copy-paste and relying on composition over inheritance.
  *
  * Examples:
+ * - A text editor : all events are Command which can be undone, stacked and saved. 
  * - Symfony2: SF2 Commands that can be run from the CLI are built with just the Command pattern in mind
  * - big CLI tools use subcommands to distribute various tasks and pack them in "modules", each of these
  *   can be implemented with the Command pattern (e.g. vagrant)
  *
  */
-interface CommandInterface
+interface Command
 {
+
     /**
      * this is the most important method in the Command pattern,
-     * all config options and parameters should go into the constructor
-     *
-     * @return mixed
+     * The Receiver go in the constructor.
      */
     public function execute();
 }
-
-class EchoCommand implements CommandInterface
-{
-    public function __construct($what)
-    {
-        $this->what = (string)$what;
-    }
-
-    public function execute()
-    {
-        echo $this->what;
-    }
-}

Command/HelloCommand.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace DesignPatterns\Command;
+
+/**
+ * This concrete command calls "print" on the Receiver, but an external
+ * invoker just know he can call "execute" 
+ */
+class HelloCommand implements Command
+{
+
+    protected $output;
+
+    /**
+     * Each concrete command is builded with different receivers.
+     * Can be one, many, none or even other Command in parameters 
+     */
+    public function __construct(Receiver $console)
+    {
+        $this->output = $console;
+    }
+
+    public function execute()
+    {
+        // sometimes, there is no receiver and this is the command which 
+        // does all the work
+        $this->output->write('Hello World');
+    }
+
+}

Command/Invoker.php

@@ -0,0 +1,34 @@
+<?php
+
+/*
+ * DesignPatternPHP
+ */
+
+namespace DesignPatterns\Command;
+
+/**
+ * Invoker is using the command given to it.
+ * Example : an Application in SF2
+ */
+class Invoker
+{
+
+    protected $command;
+
+    /**
+     * In the invoker we find this kind of method for subscribing the command.
+     * There can be also a stack, a list, a fixed set...
+     */
+    public function setCommand(Command $cmd)
+    {
+        $this->command = $cmd;
+    }
+
+    public function run()
+    {
+        // here is a key feature of the invoker
+        // the invoker is the same whatever is the command
+        $this->command->execute();
+    }
+
+}

Command/Receiver.php

@@ -0,0 +1,20 @@
+<?php
+
+/*
+ * DesignPatternPHP
+ */
+
+namespace DesignPatterns\Command;
+
+/**
+ * Receiver is specific service with its own contract and can be only concrete
+ */
+class Receiver
+{
+
+    public function write($str)
+    {
+        echo $str;
+    }
+
+}

Tests/Command/CommandTest.php

@@ -0,0 +1,36 @@
+<?php
+
+/*
+ * DesignPatternPHP
+ */
+
+namespace DesignPatterns\Tests\Command;
+
+use DesignPatterns\Command\Invoker;
+use DesignPatterns\Command\Receiver;
+use DesignPatterns\Command\HelloCommand;
+
+/**
+ * CommandTest has the role of the Client in the Command Pattern
+ */
+class CommandTest extends \PHPUnit_Framework_TestCase
+{
+
+    protected $invoker;
+    protected $receiver;
+
+    protected function setUp()
+    {
+        // this is the context of the application
+        $this->invoker = new Invoker();
+        $this->receiver = new Receiver();
+    }
+
+    public function testInvocation()
+    {
+        $this->invoker->setCommand(new HelloCommand($this->receiver));
+        $this->expectOutputString('Hello World');
+        $this->invoker->run();
+    }
+
+}