PhpDoc cleanup

src/pjdietz/WellRESTed/Client.php

@@ -19,7 +19,7 @@ use pjdietz\WellRESTed\Interfaces\ResponseInterface;
  */
 class Client
 {
-    /** @var array cURL options */
+    /** @var array Map of cURL options with cURL constants as keys */
     private $curlOpts;
 
     /**

src/pjdietz/WellRESTed/Exceptions/CurlException.php

@@ -11,7 +11,7 @@
 namespace pjdietz\WellRESTed\Exceptions;
 
 /**
- * Exception related to a cURL operation. The message and code should correspond
+ * Exception related to a cURL operations. The message and code should correspond
  * to the cURL error and error number that caused the excpetion.
  */
 class CurlException extends WellRESTedException

src/pjdietz/WellRESTed/Exceptions/HttpExceptions.php

@@ -5,10 +5,10 @@
  * error status codes. The most common are included, but you may create
  * additional subclasses if needed by subclassing HttpException.
  *
- * The HttpException classes are intended to be used with Handler subclasses
- * (pjdietz\WellRESTed\Handler). Handler::getResponse() catches HttpException
- * exceptions and converts them to responses using the exception's code as the
- * HTTP status code and the exception's message as the response body.
+ * The HttpException classes are intended to be used with Routers or Handler
+ * subclasses (pjdietz\WellRESTed\Handler). These classes will catch
+ * HttpExceptions and convert them to responses using the exception's code as
+ * the HTTP status code and the exception's message as the response body.
  *
  * @author PJ Dietz <pj@pjdietz.com>
  * @copyright Copyright 2015 by PJ Dietz

src/pjdietz/WellRESTed/Exceptions/WellRESTedException.php

@@ -13,7 +13,7 @@ namespace pjdietz\WellRESTed\Exceptions;
 use Exception;
 
 /**
- * Top level class for custom exceptions thrown by Well RESTed.
+ * Top-level class for custom exceptions thrown by WellRESTed.
  */
 class WellRESTedException extends Exception
 {

src/pjdietz/WellRESTed/Interfaces/Routes/PrefixRouteInterface.php

@@ -16,9 +16,9 @@ namespace pjdietz\WellRESTed\Interfaces\Routes;
 interface PrefixRouteInterface
 {
     /**
-     * Returns the path prefixes this maps to a target handler.
+     * Returns the path prefixes the instance maps to a target handler.
      *
-     * @return array Array of path prefixes.
+     * @return string[] List array of path prefixes.
      */
     public function getPrefixes();
 }

src/pjdietz/WellRESTed/Interfaces/Routes/StaticRouteInterface.php

@@ -16,9 +16,9 @@ namespace pjdietz\WellRESTed\Interfaces\Routes;
 interface StaticRouteInterface
 {
     /**
-     * Returns the paths this maps to a target handler.
+     * Returns the paths the instance maps to a target handler.
      *
-     * @return array Array of paths.
+     * @return string[] List array of paths.
      */
     public function getPaths();
 }

src/pjdietz/WellRESTed/Message.php

@@ -73,7 +73,7 @@ abstract class Message
     }
 
     /**
-     * Return the value of a given header, or false if it does not exist.
+     * Return the value of a given header, or null if it does not exist.
      *
      * @param string $name
      * @return string|null

src/pjdietz/WellRESTed/Request.php

@@ -15,19 +15,12 @@ use pjdietz\WellRESTed\Interfaces\RequestInterface;
 use UnexpectedValueException;
 
 /**
- * A Request instance represents an HTTP request. This class has two main uses:
- *
- * First, you can access a singleton instance via the getRequest() method that
- * represents the request sent to the server. The instance will contain the URI,
- * headers, body, etc.
- *
- * Second, you can create a custom Request and use it to obtain a Response
- * from a server through cURL.
+ * A Request instance represents an HTTP request.
  */
 class Request extends Message implements RequestInterface
 {
     /**
-     * Singleton instance derived from reading info from Apache.
+     * Singleton instance derived from reading the request sent to the server.
      *
      * @var Request
      * @static
@@ -37,7 +30,7 @@ class Request extends Message implements RequestInterface
     private $method = "GET";
     /** @var string Scheme for the request (Must be "http" or "https" */
     private $scheme;
-    /** @var string  The Hostname for the request (e.g., www.google.com) */
+    /** @var string  The Hostname for the request */
     private $hostname = "localhost";
     /** @var string   Path component of the URI for the request */
     private $path = "/";
@@ -69,7 +62,7 @@ class Request extends Message implements RequestInterface
 
     /**
      * Return a reference to the singleton instance of the Request derived
-     * from the server's information about the request sent to the script.
+     * from the server's information about the request sent to the server.
      *
      * @return Request
      * @static

src/pjdietz/WellRESTed/Response.php

@@ -152,9 +152,7 @@ class Response extends Message implements ResponseInterface
     public function setStatusCode($statusCode, $reasonPhrase = null)
     {
         $this->statusCode = (int) $statusCode;
-
         if (is_null($reasonPhrase)) {
-
             switch ($this->statusCode) {
                 case 100:
                     $text = 'Continue';
@@ -271,19 +269,14 @@ class Response extends Message implements ResponseInterface
                     $text = 'Nonstandard';
                     break;
             }
-
             $this->reasonPhrase = $text;
-
         } else {
-
             if (is_string($reasonPhrase)) {
                 $this->reasonPhrase = $reasonPhrase;
             } else {
                 throw new InvalidArgumentException('$reasonPhrase must be a string (or null to use standard HTTP Reason-Phrase');
             }
-
         }
-
     }
 
     /**

src/pjdietz/WellRESTed/RouteTable.php

@@ -23,7 +23,7 @@ use pjdietz\WellRESTed\Interfaces\Routes\StaticRouteInterface;
  */
 class RouteTable implements HandlerInterface
 {
-    /** @var array  Array of Route objects */
+    /** @var HandlerInterface[]  Array of Route objects */
     private $routes;
     /** @var array  Hash array mapping exact paths to routes */
     private $staticRoutes;
@@ -74,7 +74,7 @@ class RouteTable implements HandlerInterface
     }
 
     /**
-     * Return the response associated with the matching static route, or null if none match.
+     * Return the response from the matching static route, or null if none match.
      *
      * @param RequestInterface $request
      * @param array|null $args
@@ -91,7 +91,7 @@ class RouteTable implements HandlerInterface
     }
 
     /**
-     * Returning the best-matching prefix handler, or null if none match.
+     * Returning the response from the best-matching prefix handler, or null if none match.
      *
      * @param RequestInterface $request
      * @param array|null $args

src/pjdietz/WellRESTed/Router.php

@@ -40,11 +40,12 @@ class Router implements HandlerInterface
     /**
      * Add a route or series of routes to the Router.
      *
-     * When adding a single route, the first argument should be the path, path prefix, URI template, or regex pattern.
-     * The method will attempt to find the best type of route based on this argument and send the remainding arguments
-     * to that routes constructor. @see {RouteFactory::createRoute}
+     * When adding a single route, the first argument should be the path, path
+     * prefix, URI template, or regex pattern. The method will attempt to find
+     * the best type of route based on this argument and send the remaining
+     * arguments to the route's constructor. @see {RouteFactory::createRoute}
      *
-     * To add multiple routes, pass arrays to add where each array contains an argument list.
+     * To add multiple routes, pass arrays where each array contains an argument list.
      */
     public function add()
     {
@@ -111,7 +112,7 @@ class Router implements HandlerInterface
     }
 
     /**
-     * Dispatch the singleton Request through the router and output the response.
+     * Dispatch the server request through the router and output the response.
      *
      * Respond with a 404 Not Found if no route provides a response.
      * @param array|null $args
@@ -150,7 +151,10 @@ class Router implements HandlerInterface
     }
 
     /**
-     * Prepare a response indicating a 404 Not Found error
+     * Prepare a response indicating a 404 Not Found error.
+     *
+     * Rather than subclassing and overriding this method, you may provide an
+     * error handler for status code 404. (@see setErrorHandler)
      *
      * @param RequestInterface $request
      * @return ResponseInterface
@@ -168,7 +172,7 @@ class Router implements HandlerInterface
     }
 
     /**
-     * Obtain a response from the register error handlers.
+     * Obtain a response from the registered error handlers.
      *
      * @param int $status HTTP Status Code
      * @param RequestInterface $request The original request
@@ -197,13 +201,13 @@ class Router implements HandlerInterface
     /**
      * Wraps the getResponse method in a try-catch.
      *
-     * In an HttpException is caught while trying to get a response, the method returns a response based on the
-     * HttpException's error code and message.
+     * In an HttpException is caught while trying to get a response, the method
+     * returns a response based on the HttpException's error code and message.
      *
      * @param HandlerInterface $handler The Route or Handler to try.
      * @param RequestInterface $request The incoming request.
      * @param array $args The array of arguments.
-     * @return null|Response
+     * @return Response
      */
     private function tryResponse($handler, $request, $args)
     {

src/pjdietz/WellRESTed/Routes/BaseRoute.php

@@ -27,10 +27,15 @@ abstract class BaseRoute implements HandlerInterface
      * Create a new route that will dispatch an instance of the given handler.
      *
      * $target may be:
-     * - A callable expecting no arguments that returns a HandlerInterface
+     * - A callable
      * - A string containing the fully qualified class of a HandlerInterface
      * - A HandlerInterface instance
      *
+     * Callable targets should expect to receive the same arguments as would
+     * be passed to a HandlerInterface's getResponse() method. The callable
+     * should return a HandlerInterface instance, a ResponseInterface instance,
+     * or null.
+     *
      * @param mixed $target Handler to dispatch
      */
     public function __construct($target)
@@ -39,7 +44,7 @@ abstract class BaseRoute implements HandlerInterface
     }
 
     /**
-     * Return the handled response from the target.
+     * Return the handled response.
      *
      * @param RequestInterface $request The request to respond to.
      * @param array|null $args Optional additional arguments.

src/pjdietz/WellRESTed/Routes/PrefixRoute.php

@@ -12,6 +12,7 @@ namespace pjdietz\WellRESTed\Routes;
 
 use InvalidArgumentException;
 use pjdietz\WellRESTed\Interfaces\RequestInterface;
+use pjdietz\WellRESTed\Interfaces\ResponseInterface;
 use pjdietz\WellRESTed\Interfaces\Routes\PrefixRouteInterface;
 
 /**
@@ -19,25 +20,27 @@ use pjdietz\WellRESTed\Interfaces\Routes\PrefixRouteInterface;
  */
 class PrefixRoute extends BaseRoute implements PrefixRouteInterface
 {
-    /** @var array List of static URI paths */
+    /** @var string[] List of static URI path prefixes*/
     private $prefixes;
 
     /**
-     * Create a new StaticRoute for a given path or paths and a handler class.
+     * Create a new PrefixRoute for a given prefix or prefixes and a handler class.
      *
-     * @param string|array $path Path or list of paths the request must match
-     * @param string $target Fully qualified name to an autoloadable handler class.
+     * @param string|string[] $prefix Path or list of paths the request must match
+     * @param mixed $target Handler to dispatch
      * @throws \InvalidArgumentException
+     *
+     * @see BaseRoute for details about $target
      */
-    public function __construct($path, $target)
+    public function __construct($prefix, $target)
     {
         parent::__construct($target);
-        if (is_string($path)) {
-            $this->prefixes = array($path);
-        } elseif (is_array($path)) {
-            $this->prefixes = $path;
+        if (is_string($prefix)) {
+            $this->prefixes = array($prefix);
+        } elseif (is_array($prefix)) {
+            $this->prefixes = $prefix;
         } else {
-            throw new InvalidArgumentException("$path must be a string or array of string");
+            throw new InvalidArgumentException("$prefix must be a string or array of string");
         }
     }
 
@@ -45,13 +48,11 @@ class PrefixRoute extends BaseRoute implements PrefixRouteInterface
     /* HandlerInterface */
 
     /**
-     * Return the response issued by the handler class or null.
+     * Return the handled response.
      *
-     * A null return value indicates that this route failed to match the request.
-     *
-     * @param RequestInterface $request
-     * @param array $args
-     * @return null|\pjdietz\WellRESTed\Interfaces\ResponseInterface
+     * @param RequestInterface $request The request to respond to.
+     * @param array|null $args Optional additional arguments.
+     * @return ResponseInterface
      */
     public function getResponse(RequestInterface $request, array $args = null)
     {
@@ -68,9 +69,9 @@ class PrefixRoute extends BaseRoute implements PrefixRouteInterface
     /* PrefixRouteInterface */
 
     /**
-     * Returns the path prefixes this maps to a target handler.
+     * Returns the path prefixes the instance maps to a target handler.
      *
-     * @return array Array of path prefixes.
+     * @return string[] List array of path prefixes.
      */
     public function getPrefixes()
     {

src/pjdietz/WellRESTed/Routes/RegexRoute.php

@@ -12,6 +12,7 @@ namespace pjdietz\WellRESTed\Routes;
 
 use pjdietz\WellRESTed\Exceptions\ParseException;
 use pjdietz\WellRESTed\Interfaces\RequestInterface;
+use pjdietz\WellRESTed\Interfaces\ResponseInterface;
 
 /**
  * Maps a regular expression pattern for a URI path to a Handler
@@ -22,10 +23,13 @@ class RegexRoute extends BaseRoute
     private $pattern;
 
     /**
-     * Create a new route mapping a regex pattern to a handler class name.
+     * Create a new route mapping a regex pattern to a handler.
      *
      * @param string $pattern Regular expression the path must match.
-     * @param string $target Fully qualified name to an autoloadable handler class.
+     * @param mixed $target Handler to dispatch
+     * @throws \InvalidArgumentException
+     *
+     * @see BaseRoute for details about $target
      */
     public function __construct($pattern, $target)
     {
@@ -37,14 +41,14 @@ class RegexRoute extends BaseRoute
     /* HandlerInterface */
 
     /**
-     * Return the response issued by the handler class or null.
+     * Return the handled response 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
+     * @param RequestInterface $request The request to respond to.
+     * @param array|null $args Optional additional arguments.
+     * @return ResponseInterface The handled response.
+     * @throws ParseException
      */
     public function getResponse(RequestInterface $request, array $args = null)
     {
@@ -58,7 +62,6 @@ class RegexRoute extends BaseRoute
         } elseif ($matched === false) {
             throw new ParseException("Invalid regular expression: " . $this->getPattern());
         }
-
         return null;
     }
 

src/pjdietz/WellRESTed/Routes/RouteFactory.php

@@ -19,10 +19,11 @@ use ReflectionClass;
 class RouteFactory
 {
     /**
-     * Create and return a route given a string path, a handler, and optional extra arguments.
+     * Create and return a route given a string path, a handler, and optional
+     * extra arguments.
      *
-     * The method will determine the most appropriate route subclass to use and will forward the arguments
-     * on to the subclass's constructor.
+     * The method will determine the most appropriate route subclass to use
+     * and will forward the arguments on to the subclass's constructor.
      *
      * - Paths with no special characters will generate StaticRoutes
      * - Paths ending with * will generate PrefixRoutes

src/pjdietz/WellRESTed/Routes/StaticRoute.php

@@ -12,6 +12,7 @@ namespace pjdietz\WellRESTed\Routes;
 
 use InvalidArgumentException;
 use pjdietz\WellRESTed\Interfaces\RequestInterface;
+use pjdietz\WellRESTed\Interfaces\ResponseInterface;
 use pjdietz\WellRESTed\Interfaces\Routes\StaticRouteInterface;
 
 /**
@@ -19,15 +20,17 @@ use pjdietz\WellRESTed\Interfaces\Routes\StaticRouteInterface;
  */
 class StaticRoute extends BaseRoute implements StaticRouteInterface
 {
-    /** @var array List of static URI paths */
+    /** @var string[] List of static URI paths */
     private $paths;
 
     /**
-     * Create a new StaticRoute for a given path or paths and a handler class.
+     * Create a new StaticRoute for a given path or paths and a handler.
      *
      * @param string|array $path Path or list of paths the request must match
-     * @param string $target Fully qualified name to an autoloadable handler class.
+     * @param mixed $target Handler to dispatch
      * @throws \InvalidArgumentException
+     *
+     * @see BaseRoute for details about $target
      */
     public function __construct($path, $target)
     {
@@ -45,13 +48,11 @@ class StaticRoute extends BaseRoute implements StaticRouteInterface
     /* HandlerInterface */
 
     /**
-     * Return the response issued by the handler class or null.
+     * Return the handled response.
      *
-     * A null return value indicates that this route failed to match the request.
-     *
-     * @param RequestInterface $request
-     * @param array $args
-     * @return null|\pjdietz\WellRESTed\Interfaces\ResponseInterface
+     * @param RequestInterface $request The request to respond to.
+     * @param array|null $args Optional additional arguments.
+     * @return ResponseInterface
      */
     public function getResponse(RequestInterface $request, array $args = null)
     {
@@ -65,9 +66,9 @@ class StaticRoute extends BaseRoute implements StaticRouteInterface
     /* StaticRouteInterface */
 
     /**
-     * Returns the paths this maps to a target handler.
+     * Returns the paths the instance maps to a target handler.
      *
-     * @return array Array of paths.
+     * @return string[] List array of paths.
      */
     public function getPaths()
     {

src/pjdietz/WellRESTed/Routes/TemplateRoute.php

@@ -30,14 +30,16 @@ class TemplateRoute extends RegexRoute
     const URI_TEMPLATE_EXPRESSION_RE = '/{([[a-zA-Z][a-zA-Z0-_]*)}/';
 
     /**
-     * Create a new route that matches a URI template to a Handler.
+     * Create a new route that matches a URI template to a handler.
      *
      * Optionally provide patterns for the variables in the template.
      *
      * @param string $template URI template the path must match
-     * @param string $target Fully qualified name to an autoloadable handler class
+     * @param mixed $target Handler to dispatch
      * @param string $defaultPattern Regular expression for variables
-     * @param array|null $variablePatterns Map of variable names and regular expression
+     * @param array $variablePatterns Map of variable names and partial regular expression
+     *
+     * @see BaseRoute for details about $target
      */
     public function __construct(
         $template,