Make routines accept instances that are callable.

In other words, instances of classes that implement the __invoke()
method.
To accept class names instead of only instances we need to change
the validation of callable objects in Routine\AbstractRoutine,
something that would be nice to have. :)

Also created a *src* directory inside tests to put classes related
to tests only (stubs). Let me know if this bothers you a lot, I
still think that this is better than declaring multiple namespaces
on files.

Author: Augusto Pascutti

README.md

@@ -291,6 +291,11 @@ Respect\Rest uses a different approach to validate route parameters:
     })->when(function($documentId) {
         return is_numeric($documentId) && $documentId > 0;
     });
+    // Routines can also be called using class and method names.
+    $r3->get('/documents/*', function($documentId) {
+        /** do something */
+    })->when('SomeClass_name', 'someMethod_name');
+    // You can also pass any instance that implements the __invoke() magic method to any routine.
 ```
 
   1. This will match the route only if the callback on *when* is matched.

library/Respect/Rest/Routines/AbstractSyncedRoutine.php

@@ -5,6 +5,8 @@
 use InvalidArgumentException;
 use ReflectionFunction;
 use ReflectionMethod;
+use ReflectionObject;
+use Closure;
 use Respect\Rest\Routes\AbstractRoute;
 
 /** Base class for routines that sync parameters */
@@ -15,7 +17,15 @@ abstract class AbstractSyncedRoutine extends AbstractRoutine implements ParamSyn
 
     public function getParameters()
     {
-        return $this->getReflection()->getParameters();
+        $reflection = $this->getReflection();
+        if (!$reflection instanceof ReflectionObject)
+            return $this->getReflection()->getParameters();
+
+        $constructorReflection = $reflection->getConstructor();
+        if (is_null($constructorReflection))
+            return array();
+        else
+            return $constructorReflection->getParameters();
     }
 
     /** Returns a concrete ReflectionFunctionAbstract for this routine callback */
@@ -24,8 +34,10 @@ protected function getReflection()
         $callback = $this->getCallback();
         if (is_array($callback))
             return new ReflectionMethod($callback[0], $callback[1]);
-        else
+        else if ($callback instanceof Closure)
             return new ReflectionFunction($callback);
+        else
+            return new ReflectionObject($callback);
     }
 
 }

tests/bootstrap.php

@@ -12,6 +12,7 @@
         $paths[] = $path;
 }
 
+$paths[] = realpath(__DIR__.DIRECTORY_SEPARATOR.'src');
 natsort($paths);
 array_unshift($paths, dirname(__DIR__) .'/library');
 set_include_path(implode(PATH_SEPARATOR, array_unique($paths)));

tests/legacy/Respect/Rest/Routines/AbstractSyncedRoutineTest.php

@@ -1,6 +1,8 @@
 <?php
 namespace Respect\Rest\Routines;
 
+use Stubs\Routines\ByClassWithInvoke;
+
 /**
  * @covers Respect\Rest\Routines\ParamSynced
  * @author Nick Lombard <github@jigsoft.co.za>
@@ -59,7 +61,7 @@ public function test_getParameters_with_an_array()
                          ->setMethods(array('getCallback'))
                          ->disableOriginalConstructor()
                          ->getMock();
-        $stub->expects($this->once())
+        $stub->expects($this->any())
              ->method('getCallback')
              ->will($this->returnValue($callback));
 
@@ -85,7 +87,7 @@ public function test_getParameters_with_function()
                          ->setMethods(array('getCallback'))
                          ->disableOriginalConstructor()
                          ->getMock();
-        $stub->expects($this->once())
+        $stub->expects($this->any())
              ->method('getCallback')
              ->will($this->returnValue($callback));
 
@@ -98,4 +100,30 @@ public function test_getParameters_with_function()
             $result
         );
     }
+
+    /**
+     * @covers Respect\Rest\Routines\AbstractSyncedRoutine
+     * @covers Respect\Rest\Routines\AbstractRoutine
+     */
+    public function  test_getParameters_with_callable_instance()
+    {
+        $stub     = new ByClassWithInvoke;
+        $this->assertTrue(
+            is_callable($stub),
+            'Callable instance does not pass the is_callable test.'
+        );
+        $class    = 'Respect\Rest\Routines\AbstractSyncedRoutine';
+        $callback = function($name) { return 'Hello '.$name; };
+        $routine  = $this->getMockBuilder($class)
+                         ->setMethods(array('getCallback'))
+                         ->disableOriginalConstructor()
+                         ->getMock();
+        $routine->expects($this->any())
+                ->method('getCallback')
+                ->will($this->returnValue($stub));
+        $this->assertCount(
+            $expected = 0,
+            $result   = $routine->getParameters()
+        );
+    }
 }

tests/legacy/Respect/Rest/Routines/ByTest.php

@@ -3,6 +3,7 @@
 
 use Respect\Rest\Request,
     Respect\Rest\Router;
+use Stubs\Routines\ByClassWithInvoke;
 
 /**
  * @covers Respect\Rest\Routines\By
@@ -55,4 +56,23 @@ public function test_by_on_a_route()
             (string) $router->dispatch('GET', '/')
         );
     }
+
+    public function test_by_with_a_callable_class_on_a_route()
+    {
+        $router  = new Router;
+        $routine = new ByClassWithInvoke;
+        $router->get('/', function() { return 'route'; })
+               ->by($routine);
+        // By does not affect the output of the route.
+        $this->assertEquals(
+            $expected = 'route',
+            (string) $router->dispatch('GET', '/')
+        );
+        $this->assertAttributeEquals(
+            $expected = true,
+            'invoked',
+            $routine,
+            'Routine was not invoked!'
+        );
+    }
 }

tests/legacy/Respect/Rest/Routines/WhenTest.php

@@ -1,6 +1,10 @@
 <?php
 namespace Respect\Rest\Routines {
-use Respect\Rest\Request;
+
+use Respect\Rest\Request,
+    Respect\Rest\Router;
+use Stubs\Routines\WhenAlwaysTrue;
+
 /**
  * @covers Respect\Rest\Routines\When
  * @author Nick Lombard <github@jigsoft.co.za>
@@ -53,6 +57,25 @@ public function testWhen()
         $this->assertFalse($alias->when($request, $params));
         $this->assertArrayHasKey('HTTP/1.1 400', $header);
     }
+
+    public function test_when_with_a_callable_class_within_a_route()
+    {
+        $router  = new Router;
+        $routine = new WhenAlwaysTrue;
+        $router->get('/', function() { return 'route'; })
+               ->by($routine);
+        // By does not affect the output of the route.
+        $this->assertEquals(
+            $expected = 'route',
+            (string) $router->dispatch('GET', '/')
+        );
+        $this->assertAttributeEquals(
+            $expected = true,
+            'invoked',
+            $routine,
+            'Routine was not invoked!'
+        );
+    }
 }
 
     if (!function_exists(__NAMESPACE__.'\\header')) {

tests/src/Stubs/Routines/ByClassWithInvoke.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Stubs\Routines;
+
+class ByClassWithInvoke
+{
+    public $invoked = false;
+
+    public function __invoke()
+    {
+        $this->invoked = true;
+        return __CLASS__;
+    }
+}

tests/src/Stubs/Routines/WhenAlwaysTrue.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Stubs\Routines;
+
+class WhenAlwaysTrue
+{
+    public $invoked = false;
+
+    public function __invoke()
+    {
+        $this->invoked = true;
+        return true;
+    }
+}