From d0ef6a62fb7992f28c0b98f10c383b21dd2bfd7f Mon Sep 17 00:00:00 2001 From: PJ Dietz Date: Tue, 29 Jan 2013 20:59:55 -0500 Subject: [PATCH] Updates to documentation for better documentation generation Refactored WellrestedException to WellRESTedException --- .../WellRESTed/Exceptions/CurlException.php | 4 ++- ...dException.php => WellRESTedException.php} | 4 ++- src/pjdietz/WellRESTed/Handler.php | 12 +++++-- src/pjdietz/WellRESTed/Message.php | 33 ++++++++++++++++++- src/pjdietz/WellRESTed/Request.php | 19 +++++++++-- src/pjdietz/WellRESTed/Response.php | 24 ++++++++++---- src/pjdietz/WellRESTed/Route.php | 32 +++++++++++------- src/pjdietz/WellRESTed/Router.php | 7 ++++ 8 files changed, 108 insertions(+), 27 deletions(-) rename src/pjdietz/WellRESTed/Exceptions/{WellrestedException.php => WellRESTedException.php} (71%) diff --git a/src/pjdietz/WellRESTed/Exceptions/CurlException.php b/src/pjdietz/WellRESTed/Exceptions/CurlException.php index 3c9efab..aa3c3bb 100644 --- a/src/pjdietz/WellRESTed/Exceptions/CurlException.php +++ b/src/pjdietz/WellRESTed/Exceptions/CurlException.php @@ -1,6 +1,8 @@ * @copyright Copyright 2013 by PJ Dietz * @license MIT @@ -12,6 +14,6 @@ namespace pjdietz\WellRESTed\Exceptions; * Exception related to a cURL operation. The message and code should correspond * to the cURL error and error number that caused the excpetion. */ -class CurlException extends WellrestedException +class CurlException extends WellRESTedException { } diff --git a/src/pjdietz/WellRESTed/Exceptions/WellrestedException.php b/src/pjdietz/WellRESTed/Exceptions/WellRESTedException.php similarity index 71% rename from src/pjdietz/WellRESTed/Exceptions/WellrestedException.php rename to src/pjdietz/WellRESTed/Exceptions/WellRESTedException.php index adcf974..1ded69b 100644 --- a/src/pjdietz/WellRESTed/Exceptions/WellrestedException.php +++ b/src/pjdietz/WellRESTed/Exceptions/WellRESTedException.php @@ -1,6 +1,8 @@ * @copyright Copyright 2013 by PJ Dietz * @license MIT @@ -13,6 +15,6 @@ use \Exception; /** * Top level class for custom exceptions thrown by Well RESTed. */ -class WellrestedException extends Exception +class WellRESTedException extends Exception { } diff --git a/src/pjdietz/WellRESTed/Handler.php b/src/pjdietz/WellRESTed/Handler.php index 9533f7a..db73217 100644 --- a/src/pjdietz/WellRESTed/Handler.php +++ b/src/pjdietz/WellRESTed/Handler.php @@ -1,6 +1,8 @@ * @copyright Copyright 2013 by PJ Dietz * @license MIT @@ -11,7 +13,7 @@ namespace pjdietz\WellRESTed; /** * A Handler issues a response for a given resource. * - * @property-read Response response The Response to the request + * @property-read Response response The Response to the request */ class Handler { @@ -56,9 +58,11 @@ class Handler } // ------------------------------------------------------------------------- - // !Accessors + // Accessors /** + * Magic function for properties + * * @param string $propertyName * @return mixed */ @@ -71,6 +75,8 @@ class Handler } /** + * Return the instance's Reponse + * * @return Response */ public function getResponse() @@ -119,7 +125,7 @@ class Handler } // ------------------------------------------------------------------------- - // !HTTP Methods + // HTTP Methods // Each of these methods corresponds to a standard HTTP method. Each method // has no arguments and returns nothing, but should affect the instance's diff --git a/src/pjdietz/WellRESTed/Message.php b/src/pjdietz/WellRESTed/Message.php index d51acb2..32ce5da 100644 --- a/src/pjdietz/WellRESTed/Message.php +++ b/src/pjdietz/WellRESTed/Message.php @@ -1,6 +1,8 @@ * @copyright Copyright 2013 by PJ Dietz * @license MIT @@ -56,9 +58,11 @@ abstract class Message protected $protocolVersion = '1.1'; // ------------------------------------------------------------------------- - // !Accessors + // Accessors /** + * Magic accessor method + * * @param string $propertyName * @return mixed */ @@ -71,6 +75,8 @@ abstract class Message } /** + * Magic accessor method + * * @param string $propertyName * @param $value */ @@ -83,6 +89,8 @@ abstract class Message } /** + * Magic accessor method + * * @param string $propertyName * @return mixed */ @@ -95,6 +103,8 @@ abstract class Message } /** + * Magic accessor method + * * @param string $propertyName */ public function __unset($propertyName) @@ -126,6 +136,8 @@ abstract class Message } /** + * Return if the body is set + * * @return bool */ public function issetBody() @@ -133,6 +145,9 @@ abstract class Message return isset($this->body); } + /** + * Unset the body property + */ public function unsetBody() { unset($this->body); @@ -246,6 +261,8 @@ abstract class Message } /** + * Return the protocol (e.g., HTTP) + * * @return string */ public function getProtocol() @@ -278,6 +295,8 @@ abstract class Message } /** + * Return if the protocol property is set. + * * @return bool */ public function issetProtocol() @@ -285,12 +304,17 @@ abstract class Message return isset($this->protocol); } + /** + * Unset the protocol property. + */ public function unsetProtocol() { unset($this->protocol); } /** + * Return the version portion of the protocol. For HTTP/1.1, this is 1.1 + * * @return string */ public function getProtocolVersion() @@ -299,6 +323,8 @@ abstract class Message } /** + * Assign a new protocol version + * * @param string $protocolVersion */ public function setProtocolVersion($protocolVersion) @@ -307,6 +333,8 @@ abstract class Message } /** + * Return if the version portion of the protocol is set. + * * @return bool */ public function issetProtocolVersion() @@ -314,6 +342,9 @@ abstract class Message return isset($this->protocolVersion); } + /** + * Unset the version portion of the protocol. + */ public function unsetProtocolVersion() { unset($this->protocolVersion); diff --git a/src/pjdietz/WellRESTed/Request.php b/src/pjdietz/WellRESTed/Request.php index 65ea068..d517c31 100644 --- a/src/pjdietz/WellRESTed/Request.php +++ b/src/pjdietz/WellRESTed/Request.php @@ -1,6 +1,8 @@ * @copyright Copyright 2013 by PJ Dietz * @license MIT @@ -26,8 +28,6 @@ namespace pjdietz\WellRESTed; * @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.) - * - * @package WellRESTed */ class Request extends Message { @@ -75,9 +75,11 @@ class Request extends Message static protected $theRequest; // ------------------------------------------------------------------------- - // !Accessors + // Accessors /** + * Return the hostname portion of the URI + * * @return string */ public function getHostname() @@ -86,6 +88,8 @@ class Request extends Message } /** + * Assign the hostname portion of the URI + * * @param string $hostname */ public function setHostname($hostname) @@ -94,6 +98,8 @@ class Request extends Message } /** + * Return if the hostname portion of the URI is set. + * * @return bool */ public function issetHostName() @@ -101,12 +107,17 @@ class Request extends Message return isset($this->hostname); } + /** + * Unset the hostname portion of the URI. + */ public function unsetHostname() { unset($this->hostname); } /** + * Return the method (e.g., GET, POST, PUT, DELETE) + * * @return string */ public function getMethod() @@ -115,6 +126,8 @@ class Request extends Message } /** + * Assign the method (e.g., GET, POST, PUT, DELETE) + * * @param string $method */ public function setMethod($method) diff --git a/src/pjdietz/WellRESTed/Response.php b/src/pjdietz/WellRESTed/Response.php index 454844b..1ed06e8 100644 --- a/src/pjdietz/WellRESTed/Response.php +++ b/src/pjdietz/WellRESTed/Response.php @@ -1,6 +1,8 @@ * @copyright Copyright 2013 by PJ Dietz * @license MIT @@ -8,13 +10,15 @@ namespace pjdietz\WellRESTed; +use \InvalidArgumentException; + /** * 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 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" */ class Response extends Message { @@ -61,7 +65,7 @@ class Response extends Message } // ------------------------------------------------------------------------- - // !Accessors + // Accessors /** * Provide a new entity body for the respone. @@ -81,6 +85,8 @@ class Response extends Message } /** + * Return the portion of the status line explaining the status. + * * @return string */ public function getReasonPhrase() @@ -89,6 +95,8 @@ class Response extends Message } /** + * Assign an explaination for the status code. Not normally needed. + * * @param string $statusCodeMessage */ public function setReasonPhrase($statusCodeMessage) @@ -97,6 +105,8 @@ class Response extends Message } /** + * Return the status code. + * * @return int */ public function getStatusCode() @@ -105,9 +115,11 @@ class Response extends Message } /** + * Set the status code and optionally the reason phrase explaining it. + * * @param int $statusCode * @param string|null $reasonPhrase - * @throws \InvalidArgumentException + * @throws InvalidArgumentException */ public function setStatusCode($statusCode, $reasonPhrase = null) { @@ -239,7 +251,7 @@ class Response extends Message if (is_string($reasonPhrase)) { $this->reasonPhrase = $reasonPhrase; } else { - throw new \InvalidArgumentException('$reasonPhrase must be a string (or null to use standard HTTP Reason-Phrase'); + throw new InvalidArgumentException('$reasonPhrase must be a string (or null to use standard HTTP Reason-Phrase'); } } diff --git a/src/pjdietz/WellRESTed/Route.php b/src/pjdietz/WellRESTed/Route.php index 9b71d04..1334a33 100644 --- a/src/pjdietz/WellRESTed/Route.php +++ b/src/pjdietz/WellRESTed/Route.php @@ -1,6 +1,8 @@ * @copyright Copyright 2013 by PJ Dietz * @license MIT @@ -8,24 +10,35 @@ namespace pjdietz\WellRESTed; +use \Exception; + /** * A Route connects a URI pattern to a Handler. - * - * @package WellRESTed */ class Route { + /** + * Regular expression matching URL friendly characters (i.e., letters, + * digits, hyphen and underscore) + */ const RE_SLUG = '[0-9a-zA-Z\-_]+'; + + /** Regular expression matching digitis */ const RE_NUM = '[0-9]+'; + + /** Regular expression matching letters */ const RE_ALPHA = '[a-zA-Z]+'; + + /** Regular expression matching letters and digits */ const RE_ALPHANUM = '[0-9a-zA-Z]+'; + /** Regular expression matching a URI template variable (e.g., {id}) */ const URI_TEMPLATE_EXPRESSION_RE = '/{([a-zA-Z]+)}/'; /** - * Regular Expression to use to validate a template variable. + * Default regular expression used to match template variable * - * @var string + * @property string */ static public $defaultVariablePattern = self::RE_SLUG; @@ -61,7 +74,7 @@ class Route * @param string $uriTemplate * @param string $handler * @param array $variables - * @throws \Exception + * @throws Exception * @return Route */ static public function newFromUriTemplate( @@ -84,12 +97,7 @@ class Route $pattern .= '\/'; // Is this part an expression or a literal? - if (preg_match( - self::URI_TEMPLATE_EXPRESSION_RE, - $part, - $matches - ) - ) { + if (preg_match(self::URI_TEMPLATE_EXPRESSION_RE, $part, $matches)) { // This part of the path is an expresion. @@ -115,7 +123,7 @@ class Route } else { // Not sure why this would happen. - throw new \Exception('Invalid URI Template.'); + throw new Exception('Invalid URI Template.'); } } else { diff --git a/src/pjdietz/WellRESTed/Router.php b/src/pjdietz/WellRESTed/Router.php index 36e4bf3..ea12efe 100644 --- a/src/pjdietz/WellRESTed/Router.php +++ b/src/pjdietz/WellRESTed/Router.php @@ -1,6 +1,8 @@ * @copyright Copyright 2013 by PJ Dietz * @license MIT @@ -18,6 +20,7 @@ class Router { /** * Array of Route objects + * * @var array */ protected $routes; @@ -41,6 +44,8 @@ class Router } /** + * Return the Response built by the Handler based on the Request + * * @param Request $request * @return Response */ @@ -68,6 +73,8 @@ class Router } /** + * Prepare a Resonse indicating a 404 Not Found error + * * @param Request $request * @return Response */