From aa06181e40cf19061e678331f8ecd87fc8733a8f Mon Sep 17 00:00:00 2001 From: PJ Dietz Date: Sun, 29 Jun 2014 10:43:39 -0400 Subject: [PATCH] Refactor DispatcherInterface to HandlerInterface Update file doc blocks Code inspection --- .../WellRESTed/Exceptions/CurlException.php | 2 +- .../WellRESTed/Exceptions/ParseException.php | 18 ++++++++++ src/pjdietz/WellRESTed/Handler.php | 27 +++++++------- .../Interfaces/DispatcherInterface.php | 18 ---------- .../Interfaces/HandlerInterface.php | 26 ++++++++++++++ .../Interfaces/RequestInterface.php | 2 +- .../Interfaces/ResponseInterface.php | 2 +- .../Interfaces/RoutableInterface.php | 12 ------- src/pjdietz/WellRESTed/Message.php | 8 +---- src/pjdietz/WellRESTed/Request.php | 18 +++------- src/pjdietz/WellRESTed/Response.php | 7 +--- src/pjdietz/WellRESTed/RouteBuilder.php | 36 +++++++++++++++---- src/pjdietz/WellRESTed/Router.php | 32 ++++++++--------- src/pjdietz/WellRESTed/Routes/BaseRoute.php | 12 +++---- src/pjdietz/WellRESTed/Routes/RegexRoute.php | 6 ++-- src/pjdietz/WellRESTed/Routes/StaticRoute.php | 6 ++-- 16 files changed, 125 insertions(+), 107 deletions(-) create mode 100644 src/pjdietz/WellRESTed/Exceptions/ParseException.php delete mode 100644 src/pjdietz/WellRESTed/Interfaces/DispatcherInterface.php create mode 100644 src/pjdietz/WellRESTed/Interfaces/HandlerInterface.php delete mode 100644 src/pjdietz/WellRESTed/Interfaces/RoutableInterface.php diff --git a/src/pjdietz/WellRESTed/Exceptions/CurlException.php b/src/pjdietz/WellRESTed/Exceptions/CurlException.php index aa3c3bb..9034ac9 100644 --- a/src/pjdietz/WellRESTed/Exceptions/CurlException.php +++ b/src/pjdietz/WellRESTed/Exceptions/CurlException.php @@ -4,7 +4,7 @@ * pjdietz\WellRESTed\Exceptions\CurlException * * @author PJ Dietz - * @copyright Copyright 2013 by PJ Dietz + * @copyright Copyright 2014 by PJ Dietz * @license MIT */ diff --git a/src/pjdietz/WellRESTed/Exceptions/ParseException.php b/src/pjdietz/WellRESTed/Exceptions/ParseException.php new file mode 100644 index 0000000..e89a5cc --- /dev/null +++ b/src/pjdietz/WellRESTed/Exceptions/ParseException.php @@ -0,0 +1,18 @@ + + * @copyright Copyright 2014 by PJ Dietz + * @license MIT + */ + +namespace pjdietz\WellRESTed\Exceptions; + +/** + * Exception related to a parsing data. + */ +class ParseException extends WellRESTedException +{ +} diff --git a/src/pjdietz/WellRESTed/Handler.php b/src/pjdietz/WellRESTed/Handler.php index 79be1f7..686399f 100644 --- a/src/pjdietz/WellRESTed/Handler.php +++ b/src/pjdietz/WellRESTed/Handler.php @@ -4,36 +4,41 @@ * pjdietz\WellRESTed\Handler * * @author PJ Dietz - * @copyright Copyright 2013 by PJ Dietz + * @copyright Copyright 2014 by PJ Dietz * @license MIT */ namespace pjdietz\WellRESTed; -use pjdietz\WellRESTed\Interfaces\DispatcherInterface; +use pjdietz\WellRESTed\Interfaces\HandlerInterface; use pjdietz\WellRESTed\Interfaces\ResponseInterface; -use pjdietz\WellRESTed\Interfaces\RoutableInterface; +use pjdietz\WellRESTed\Interfaces\RequestInterface; /** - * A Handler issues a response for a given resource. + * Responds to a request based on the HTTP method. * - * @property-read ResponseInterface response The Response to the request + * To use Handler, create a subclass and implement the methods for any HTTP + * verbs you would like to support. (get() for GET, post() for POST, etc). + * + * - Access the request via the protected member $this->request + * - Access a map of arguments via $this->args (e.g., URI path variables) + * - Modify $this->response to provide the response the instance will return */ -abstract class Handler implements DispatcherInterface +abstract class Handler implements HandlerInterface { - /** @var array Matches array from the preg_match() call used to find this Handler */ + /** @var array Map of variables to suppliement the request, usually path variables. */ protected $args; - /** @var RoutableInterface The HTTP request to respond to. */ + /** @var RequestInterface The HTTP request to respond to. */ protected $request; /** @var ResponseInterface The HTTP response to send based on the request. */ protected $response; /** - * @param RoutableInterface $request + * @param RequestInterface $request * @param array|null $args * @return ResponseInterface */ - public function getResponse(RoutableInterface $request = null, $args = null) + public function getResponse(RequestInterface $request, array $args = null) { $this->request = $request; $this->args = $args; @@ -95,9 +100,7 @@ abstract class Handler implements DispatcherInterface { // The default function calls the instance's get() method, then sets // the resonse's body member to an empty string. - $this->get(); - if ($this->response->getStatusCode() == 200) { $this->response->setBody('', false); } diff --git a/src/pjdietz/WellRESTed/Interfaces/DispatcherInterface.php b/src/pjdietz/WellRESTed/Interfaces/DispatcherInterface.php deleted file mode 100644 index ec218bc..0000000 --- a/src/pjdietz/WellRESTed/Interfaces/DispatcherInterface.php +++ /dev/null @@ -1,18 +0,0 @@ - + * @copyright Copyright 2014 by PJ Dietz + * @license MIT + */ + +namespace pjdietz\WellRESTed\Interfaces; + +/** + * Provides a mechanism for obtaining a response given a request. + * @package pjdietz\WellRESTed + */ +interface HandlerInterface { + + /** + * @param RequestInterface $request The request to build a responce for. + * @param array|null $args Optional associate array of arguments. + * @return ResponseInterface|null + */ + public function getResponse(RequestInterface $request, array $args = null); + +} diff --git a/src/pjdietz/WellRESTed/Interfaces/RequestInterface.php b/src/pjdietz/WellRESTed/Interfaces/RequestInterface.php index 2ac4abb..00dee12 100644 --- a/src/pjdietz/WellRESTed/Interfaces/RequestInterface.php +++ b/src/pjdietz/WellRESTed/Interfaces/RequestInterface.php @@ -4,7 +4,7 @@ * pjdietz\WellRESTed\Interfaces\RequestInterface * * @author PJ Dietz - * @copyright Copyright 2013 by PJ Dietz + * @copyright Copyright 2014 by PJ Dietz * @license MIT */ diff --git a/src/pjdietz/WellRESTed/Interfaces/ResponseInterface.php b/src/pjdietz/WellRESTed/Interfaces/ResponseInterface.php index 51278b1..42e16ab 100644 --- a/src/pjdietz/WellRESTed/Interfaces/ResponseInterface.php +++ b/src/pjdietz/WellRESTed/Interfaces/ResponseInterface.php @@ -4,7 +4,7 @@ * pjdietz\WellRESTed\Interfaces\ResponseInterface * * @author PJ Dietz - * @copyright Copyright 2013 by PJ Dietz + * @copyright Copyright 2014 by PJ Dietz * @license MIT */ diff --git a/src/pjdietz/WellRESTed/Interfaces/RoutableInterface.php b/src/pjdietz/WellRESTed/Interfaces/RoutableInterface.php deleted file mode 100644 index db6ca98..0000000 --- a/src/pjdietz/WellRESTed/Interfaces/RoutableInterface.php +++ /dev/null @@ -1,12 +0,0 @@ - - * @copyright Copyright 2013 by PJ Dietz + * @copyright Copyright 2014 by PJ Dietz * @license MIT */ @@ -12,12 +12,6 @@ namespace pjdietz\WellRESTed; /** * Common base class for the Request and Response classes. - * - * @property string body Entity body of the message - * @property-read array headers Associative array of HTTP headers - * @property-read array headerLines Numeric array of HTTP headers - * @property string protocol The protocol, e.g. HTTP - * @property string protocolVersion The version of the protocol */ abstract class Message { diff --git a/src/pjdietz/WellRESTed/Request.php b/src/pjdietz/WellRESTed/Request.php index b5f3bb5..5c1b009 100644 --- a/src/pjdietz/WellRESTed/Request.php +++ b/src/pjdietz/WellRESTed/Request.php @@ -4,14 +4,14 @@ * pjdietz\WellRESTed\Request * * @author PJ Dietz - * @copyright Copyright 2013 by PJ Dietz + * @copyright Copyright 2014 by PJ Dietz * @license MIT */ namespace pjdietz\WellRESTed; use pjdietz\WellRESTed\Exceptions\CurlException; -use pjdietz\WellRESTed\Interfaces\RoutableInterface; +use pjdietz\WellRESTed\Interfaces\RequestInterface; /** * A Request instance represents an HTTP request. This class has two main uses: @@ -22,15 +22,8 @@ use pjdietz\WellRESTed\Interfaces\RoutableInterface; * * Second, you can create a custom Request and use it to obtain a Response * from a server through cURL. - * - * @property string hostname Hostname part of the URI - * @property string method HTTP method (GET, POST, PUT, DELETE, etc.) - * @property string path Path component of the URI for the request - * @property-read string pathParts Fragments of the path, delimited by slashes - * @property array query Associative array of query parameters - * @property array uri Full URI (protocol, hostname, path, etc.) */ -class Request extends Message implements RoutableInterface +class Request extends Message implements RequestInterface { /** * Singleton instance derived from reading info from Apache. @@ -65,11 +58,9 @@ class Request extends Message implements RoutableInterface public function __construct($uri = null, $method = 'GET') { parent::__construct(); - if (!is_null($uri)) { $this->setUri($uri); } - $this->method = $method; } @@ -89,7 +80,6 @@ class Request extends Message implements RoutableInterface $request->readHttpRequest(); self::$theRequest = $request; } - return self::$theRequest; } @@ -398,7 +388,7 @@ class Request extends Message implements RoutableInterface // Make a reponse to populate and return with data obtained via cURL. $resp = new Response(); - $resp->statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); + $resp->setStatusCode(curl_getinfo($ch, CURLINFO_HTTP_CODE)); // Split the result into headers and body. $headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE); diff --git a/src/pjdietz/WellRESTed/Response.php b/src/pjdietz/WellRESTed/Response.php index 28de592..b90b749 100644 --- a/src/pjdietz/WellRESTed/Response.php +++ b/src/pjdietz/WellRESTed/Response.php @@ -4,7 +4,7 @@ * pjdietz\WellRESTed\Response * * @author PJ Dietz - * @copyright Copyright 2013 by PJ Dietz + * @copyright Copyright 2014 by PJ Dietz * @license MIT */ @@ -16,11 +16,6 @@ use pjdietz\WellRESTed\Interfaces\ResponseInterface; /** * A Response instance allows you to build an HTTP response and send it when * finished. - * - * @property string reasonPhrase Text explanation of status code. - * @property int statusCode HTTP status code - * @property-read string statusLine HTTP status line, e.g. "HTTP/1.1 200 OK" - * @property-read bool success True if the status code is 2xx */ class Response extends Message implements ResponseInterface { diff --git a/src/pjdietz/WellRESTed/RouteBuilder.php b/src/pjdietz/WellRESTed/RouteBuilder.php index 28e110c..3749711 100644 --- a/src/pjdietz/WellRESTed/RouteBuilder.php +++ b/src/pjdietz/WellRESTed/RouteBuilder.php @@ -1,21 +1,39 @@ + * @copyright Copyright 2014 by PJ Dietz + * @license MIT + */ + namespace pjdietz\WellRESTed; -use pjdietz\WellRESTed\Interfaces\DispatcherInterface; +use pjdietz\WellRESTed\Exceptions\ParseException; +use pjdietz\WellRESTed\Interfaces\HandlerInterface; use pjdietz\WellRESTed\Routes\RegexRoute; use pjdietz\WellRESTed\Routes\StaticRoute; use pjdietz\WellRESTed\Routes\TemplateRoute; use stdClass; -use UnexpectedValueException; +/** + * Class for facilitating constructing Routers. + */ class RouteBuilder { private $handlerNamespace; private $templateVariablePatterns; private $defaultVariablePattern; - public function getRoutes($data) + /** + * Contruct and return an array of routes. + * + * @param $data + * @return array + * @throws Exceptions\ParseException + */ + public function buildRoutes($data) { // Locate the list of routes. This should be one of these: // - If $data is an object, $data->routes @@ -26,7 +44,7 @@ class RouteBuilder $dataRoutes = $data->routes; $this->readConfiguration($data); } else { - throw new UnexpectedValueException("Unable to parse. Missing array of routes."); + throw new ParseException("Unable to parse. Missing array of routes."); } // Build a route instance and append it to the list. @@ -37,10 +55,14 @@ class RouteBuilder return $routes; } + public function buildRoutesFromJson($json) { + return $this->buildRoutes(json_decode($json)); + } + /** * @param stdClass|array $item - * @return DispatcherInterface - * @throws \UnexpectedValueException Parse error + * @return HandlerInterface + * @throws Exceptions\ParseException */ protected function buildRoute($item) { @@ -51,7 +73,7 @@ class RouteBuilder $handler = $this->getHandlerNamespace() . "\\" . $handler; } } else { - throw new UnexpectedValueException("Unable to parse. Route is missing a handler."); + throw new ParseException("Unable to parse. Route is missing a handler."); } // Static Route diff --git a/src/pjdietz/WellRESTed/Router.php b/src/pjdietz/WellRESTed/Router.php index b638fd5..9447333 100644 --- a/src/pjdietz/WellRESTed/Router.php +++ b/src/pjdietz/WellRESTed/Router.php @@ -4,22 +4,22 @@ * pjdietz\WellRESTed\Router * * @author PJ Dietz - * @copyright Copyright 2013 by PJ Dietz + * @copyright Copyright 2014 by PJ Dietz * @license MIT */ namespace pjdietz\WellRESTed; -use pjdietz\WellRESTed\Interfaces\DispatcherInterface; +use pjdietz\WellRESTed\Interfaces\HandlerInterface; use pjdietz\WellRESTed\Interfaces\ResponseInterface; -use pjdietz\WellRESTed\Interfaces\RoutableInterface; +use pjdietz\WellRESTed\Interfaces\RequestInterface; /** * Router * * A Router uses a table of Routes to find the appropriate Handler for a request. */ -class Router implements DispatcherInterface +class Router implements HandlerInterface { /** @var array Array of Route objects */ private $routes; @@ -33,11 +33,11 @@ class Router implements DispatcherInterface /** * Return the response built by the handler based on the request * - * @param RoutableInterface $request - * @param null $args + * @param RequestInterface $request + * @param array|null $args * @return ResponseInterface */ - public function getResponse(RoutableInterface $request, $args = null) + public function getResponse(RequestInterface $request, array $args = null) { // Use the singleton if the caller did not pass a request. if (is_null($request)) { @@ -45,7 +45,7 @@ class Router implements DispatcherInterface } foreach ($this->routes as $route) { - /** @var DispatcherInterface $route */ + /** @var HandlerInterface $route */ $responce = $route->getResponse($request, $args); if ($responce) { return $responce; @@ -58,9 +58,9 @@ class Router implements DispatcherInterface /** * Append a new route to the route route table. * - * @param DispatcherInterface $route + * @param HandlerInterface $route */ - public function addRoute(DispatcherInterface $route) + public function addRoute(HandlerInterface $route) { $this->routes[] = $route; } @@ -68,12 +68,12 @@ class Router implements DispatcherInterface /** * Append a series of routes. * - * @param array $routes List array of DispatcherInterface instances + * @param array $routes List array of HandlerInterface instances */ public function addRoutes(array $routes) { foreach ($routes as $route) { - if ($route instanceof DispatcherInterface) { + if ($route instanceof HandlerInterface) { $this->addRoute($route); } } @@ -87,10 +87,10 @@ class Router implements DispatcherInterface /** * Prepare a resonse indicating a 404 Not Found error * - * @param RoutableInterface $request + * @param RequestInterface $request * @return ResponseInterface */ - protected function getNoRouteResponse(RoutableInterface $request) + protected function getNoRouteResponse(RequestInterface $request) { $response = new Response(404); $response->setBody('No resource at ' . $request->getPath()); @@ -100,11 +100,11 @@ class Router implements DispatcherInterface /** * Prepare a response indicating a 500 Internal Server Error * - * @param RoutableInterface $request + * @param RequestInterface $request * @param string $message Optional additional message. * @return ResponseInterface */ - protected function getInternalServerErrorResponse(RoutableInterface $request, $message = '') + protected function getInternalServerErrorResponse(RequestInterface $request, $message = '') { $response = new Response(500); $response->setBody('Server error at ' . $request->getPath() . "\n" . $message); diff --git a/src/pjdietz/WellRESTed/Routes/BaseRoute.php b/src/pjdietz/WellRESTed/Routes/BaseRoute.php index 39578bd..cbea7e0 100644 --- a/src/pjdietz/WellRESTed/Routes/BaseRoute.php +++ b/src/pjdietz/WellRESTed/Routes/BaseRoute.php @@ -2,16 +2,16 @@ namespace pjdietz\WellRESTed\Routes; -use pjdietz\WellRESTed\Interfaces\DispatcherInterface; +use pjdietz\WellRESTed\Interfaces\HandlerInterface; /** * Base class for Routes. * @package pjdietz\WellRESTed\Routes */ -abstract class BaseRoute implements DispatcherInterface +abstract class BaseRoute implements HandlerInterface { /** @var string Fully qualified name for the interface for handlers */ - const DISPATCHER_INTERFACE = '\\pjdietz\\WellRESTed\\Interfaces\\DispatcherInterface'; + const DISPATCHER_INTERFACE = '\\pjdietz\\WellRESTed\\Interfaces\\HandlerInterface'; /** @var string */ private $targetClassName; @@ -25,17 +25,17 @@ abstract class BaseRoute implements DispatcherInterface } /** - * @return DispatcherInterface + * @return HandlerInterface * @throws \UnexpectedValueException */ protected function getTarget() { if (is_subclass_of($this->targetClassName, self::DISPATCHER_INTERFACE)) { - /** @var DispatcherInterface $target */ + /** @var HandlerInterface $target */ $target = new $this->targetClassName(); return $target; } else { - throw new \UnexpectedValueException("Target class must implement DispatcherInterface"); + throw new \UnexpectedValueException("Target class must implement HandlerInterface"); } } diff --git a/src/pjdietz/WellRESTed/Routes/RegexRoute.php b/src/pjdietz/WellRESTed/Routes/RegexRoute.php index 42f345d..8e68b68 100644 --- a/src/pjdietz/WellRESTed/Routes/RegexRoute.php +++ b/src/pjdietz/WellRESTed/Routes/RegexRoute.php @@ -2,7 +2,7 @@ namespace pjdietz\WellRESTed\Routes; -use pjdietz\WellRESTed\Interfaces\RoutableInterface; +use pjdietz\WellRESTed\Interfaces\RequestInterface; class RegexRoute extends BaseRoute { @@ -19,9 +19,9 @@ class RegexRoute extends BaseRoute } // ------------------------------------------------------------------------ - /* DispatcherInterface */ + /* HandlerInterface */ - public function getResponse(RoutableInterface $request, $args = null) + public function getResponse(RequestInterface $request, array $args = null) { if (preg_match($this->getPattern(), $request->getPath(), $matches)) { $target = $this->getTarget(); diff --git a/src/pjdietz/WellRESTed/Routes/StaticRoute.php b/src/pjdietz/WellRESTed/Routes/StaticRoute.php index 2cc8121..65bfaf0 100644 --- a/src/pjdietz/WellRESTed/Routes/StaticRoute.php +++ b/src/pjdietz/WellRESTed/Routes/StaticRoute.php @@ -3,7 +3,7 @@ namespace pjdietz\WellRESTed\Routes; use InvalidArgumentException; -use pjdietz\WellRESTed\Interfaces\RoutableInterface; +use pjdietz\WellRESTed\Interfaces\RequestInterface; /** * Class StaticRoute @@ -31,9 +31,9 @@ class StaticRoute extends BaseRoute } // ------------------------------------------------------------------------ - /* DispatcherInterface */ + /* HandlerInterface */ - public function getResponse(RoutableInterface $request, $args = null) + public function getResponse(RequestInterface $request, array $args = null) { $requestPath = $request->getPath(); foreach ($this->paths as $path) {