Fix documentation and add tests for RegexRoute

src/pjdietz/WellRESTed/Routes/RegexRoute.php

@@ -1,14 +1,29 @@
 <?php
 
+/**
+ * pjdietz\WellRESTed\RegexRout
+ *
+ * @author PJ Dietz <pj@pjdietz.com>
+ * @copyright Copyright 2014 by PJ Dietz
+ * @license MIT
+ */
+
 namespace pjdietz\WellRESTed\Routes;
 
+use pjdietz\WellRESTed\Exceptions\ParseException;
 use pjdietz\WellRESTed\Interfaces\RequestInterface;
 
+/**
+ * Maps a regular expression pattern for a URI path to a Handler
+ */
 class RegexRoute extends BaseRoute
 {
+    /** @var string Regular expression pattern for the route. */
     private $pattern;
 
     /**
+     * Create a new route mapping a regex pattern to a handler class name.
+     *
      * @param string $pattern Regular expression the path must match.
      * @param string $targetClassName Fully qualified name to an autoloadable handler class.
      */
@@ -21,21 +36,40 @@ class RegexRoute extends BaseRoute
     // ------------------------------------------------------------------------
     /* HandlerInterface */
 
+    /**
+     * Return the response issued by the handler class or null.
+     *
+     * A null return value indicates that this route failed to match the request.
+     *
+     * @param RequestInterface $request
+     * @param array $args
+     * @throws \pjdietz\WellRESTed\Exceptions\ParseException
+     * @return null|\pjdietz\WellRESTed\Interfaces\ResponseInterface
+     */
     public function getResponse(RequestInterface $request, array $args = null)
     {
-        if (preg_match($this->getPattern(), $request->getPath(), $matches)) {
+        $matched = @preg_match($this->getPattern(), $request->getPath(), $matches);
+        if ($matched) {
             $target = $this->getTarget();
             if (is_null($args)) {
                 $args = array();
             }
             $args = array_merge($args, $matches);
             return $target->getResponse($request, $args);
+        } elseif ($matched === false) {
+            throw new ParseException("Invalid regular expression: " . $this->getPattern());
         }
+
         return null;
     }
 
     // ------------------------------------------------------------------------
 
+    /**
+     * Return the regex pattern for the route.
+     *
+     * @return string Regex pattern
+     */
     protected function getPattern()
     {
         return $this->pattern;

test/Routes/RegexRouteTest.php

@@ -0,0 +1,80 @@
+<?php
+
+use pjdietz\WellRESTed\Routes\RegexRoute;
+
+class RegexRouteTest extends \PHPUnit_Framework_TestCase
+{
+    public static function setUpBeforeClass()
+    {
+        include_once(__DIR__ . "/../src/MockHandler.php");
+    }
+
+    /**
+     * @dataProvider matchingRouteProvider
+     */
+    public function testMatchingRoute($pattern, $path)
+    {
+        $mockRequest = $this->getMock('\pjdietz\WellRESTed\Interfaces\RequestInterface');
+        $mockRequest->expects($this->any())
+            ->method('getPath')
+            ->will($this->returnValue($path));
+
+        $route = new RegexRoute($pattern, 'MockHandler');
+        $resp = $route->getResponse($mockRequest);
+        $this->assertNotNull($resp);
+    }
+
+    public function matchingRouteProvider()
+    {
+        return array(
+            array("~/cat/[0-9]+~", "/cat/2"),
+            array("#/dog/.*#", "/dog/his-name-is-bear")
+        );
+    }
+
+    /**
+     * @dataProvider nonmatchingRouteProvider
+     */
+    public function testNonmatchingRoute($pattern, $path)
+    {
+        $mockRequest = $this->getMock('\pjdietz\WellRESTed\Interfaces\RequestInterface');
+        $mockRequest->expects($this->any())
+            ->method('getPath')
+            ->will($this->returnValue($path));
+
+        $route = new RegexRoute($pattern, 'MockHandler');
+        $resp = $route->getResponse($mockRequest);
+        $this->assertNull($resp);
+    }
+
+    public function nonmatchingRouteProvider()
+    {
+        return array(
+            array("~/cat/[0-9]+~", "/cat/molly"),
+            array("~/cat/[0-9]+~", "/dog/bear"),
+            array("#/dog/.*#", "/dog")
+        );
+    }
+
+    /**
+     * @dataProvider invalidRouteProvider
+     * @expectedException  \pjdietz\WellRESTed\Exceptions\ParseException
+     */
+    public function testInvalidRoute($pattern)
+    {
+        $mockRequest = $this->getMock('\pjdietz\WellRESTed\Interfaces\RequestInterface');
+
+        $route = new RegexRoute($pattern, 'MockHandler');
+        $resp = $route->getResponse($mockRequest);
+        $this->assertNull($resp);
+    }
+
+    public function invalidRouteProvider()
+    {
+        return array(
+            array("~/unterminated"),
+            array("/nope")
+        );
+    }
+
+}

test/Routes/StaticRouteTest.php

@@ -1,11 +1,14 @@
 <?php
 
-use pjdietz\WellRESTed\Interfaces\HandlerInterface;
-use pjdietz\WellRESTed\Response;
 use pjdietz\WellRESTed\Routes\StaticRoute;
 
 class StaticRouteTest extends \PHPUnit_Framework_TestCase
 {
+    public static function setUpBeforeClass()
+    {
+        include_once(__DIR__ . "/../src/MockHandler.php");
+    }
+
     public function testSinglePathMatch()
     {
         $path = "/";
@@ -15,7 +18,7 @@ class StaticRouteTest extends \PHPUnit_Framework_TestCase
             ->method('getPath')
             ->will($this->returnValue($path));
 
-        $route = new StaticRoute($path, 'HandlerStub');
+        $route = new StaticRoute($path, 'MockHandler');
         $resp = $route->getResponse($mockRequest);
         $this->assertEquals(200, $resp->getStatusCode());
     }
@@ -44,7 +47,7 @@ class StaticRouteTest extends \PHPUnit_Framework_TestCase
             ->method('getPath')
             ->will($this->returnValue($path));
 
-        $route = new StaticRoute($paths, 'HandlerStub');
+        $route = new StaticRoute($paths, 'MockHandler');
         $resp = $route->getResponse($mockRequest);
         $this->assertEquals(200, $resp->getStatusCode());
     }
@@ -55,7 +58,7 @@ class StaticRouteTest extends \PHPUnit_Framework_TestCase
      */
     public function testInvalidPath($path)
     {
-        $route = new StaticRoute($path, 'HandlerStub');
+        $route = new StaticRoute($path, 'MockHandler');
     }
 
     public function invalidPathsProvider()
@@ -68,16 +71,3 @@ class StaticRouteTest extends \PHPUnit_Framework_TestCase
     }
 
 }
-
-/**
- * Mini Handler class that allways returns a 200 status code Response.
- */
-class HandlerStub implements HandlerInterface
-{
-    public function getResponse(\pjdietz\WellRESTed\Interfaces\RequestInterface $request, array $args = null)
-    {
-        $resp = new Response();
-        $resp->setStatusCode(200);
-        return $resp;
-    }
-}

test/src/MockHandler.php

@@ -0,0 +1,17 @@
+<?php
+
+use pjdietz\WellRESTed\Interfaces\HandlerInterface;
+use pjdietz\WellRESTed\Response;
+
+/**
+ * Mini Handler class that allways returns a 200 status code Response.
+ */
+class MockHandler implements HandlerInterface
+{
+    public function getResponse(\pjdietz\WellRESTed\Interfaces\RequestInterface $request, array $args = null)
+    {
+        $resp = new Response();
+        $resp->setStatusCode(200);
+        return $resp;
+    }
+}