From e419aaba7dd8b744f3c690c0024b4f019f21462f Mon Sep 17 00:00:00 2001 From: PJ Dietz Date: Mon, 28 Jan 2013 22:15:33 -0500 Subject: [PATCH] Add page-level doc blocks to each script Update comments Update magic accessors Update accessor and add islet and unset methods --- .../WellRESTed/Exceptions/CurlException.php | 6 + .../Exceptions/WellrestedException.php | 6 + src/pjdietz/WellRESTed/Handler.php | 47 ++++--- src/pjdietz/WellRESTed/Message.php | 128 +++++++++++++----- src/pjdietz/WellRESTed/Request.php | 84 ++++-------- src/pjdietz/WellRESTed/Response.php | 65 ++------- src/pjdietz/WellRESTed/Route.php | 16 ++- src/pjdietz/WellRESTed/Router.php | 18 +-- 8 files changed, 190 insertions(+), 180 deletions(-) diff --git a/src/pjdietz/WellRESTed/Exceptions/CurlException.php b/src/pjdietz/WellRESTed/Exceptions/CurlException.php index 8dc306b..3c9efab 100644 --- a/src/pjdietz/WellRESTed/Exceptions/CurlException.php +++ b/src/pjdietz/WellRESTed/Exceptions/CurlException.php @@ -1,5 +1,11 @@ + * @copyright Copyright 2013 by PJ Dietz + * @license MIT + */ + namespace pjdietz\WellRESTed\Exceptions; /** diff --git a/src/pjdietz/WellRESTed/Exceptions/WellrestedException.php b/src/pjdietz/WellRESTed/Exceptions/WellrestedException.php index cb15828..adcf974 100644 --- a/src/pjdietz/WellRESTed/Exceptions/WellrestedException.php +++ b/src/pjdietz/WellRESTed/Exceptions/WellrestedException.php @@ -1,5 +1,11 @@ + * @copyright Copyright 2013 by PJ Dietz + * @license MIT + */ + namespace pjdietz\WellRESTed\Exceptions; use \Exception; diff --git a/src/pjdietz/WellRESTed/Handler.php b/src/pjdietz/WellRESTed/Handler.php index 330f050..9533f7a 100644 --- a/src/pjdietz/WellRESTed/Handler.php +++ b/src/pjdietz/WellRESTed/Handler.php @@ -1,22 +1,20 @@ + * @copyright Copyright 2013 by PJ Dietz + * @license MIT + */ + namespace pjdietz\WellRESTed; -/******************************************************************************* - * Handler - * +/** * A Handler issues a response for a given resource. * - * @package WellRESTed - * - ******************************************************************************/ - -/** - * @property Response response The Response to the request + * @property-read Response response The Response to the request */ class Handler { - /** * The HTTP request to respond to. * @@ -61,17 +59,14 @@ class Handler // !Accessors /** - * @param $name - * @return Response - * @throws \Exception + * @param string $propertyName + * @return mixed */ - public function __get($name) + public function __get($propertyName) { - switch ($name) { - case 'response': - return $this->getResponse(); - default: - throw new \Exception('Property ' . $name . ' does not exist.'); + $method = 'get' . ucfirst($propertyName); + if (method_exists($this, $method)) { + return $this->{$method}(); } } @@ -134,6 +129,8 @@ class Handler /** * Method for handling HTTP GET requests. + * + * This method should modify the instance's response member. */ protected function get() { @@ -142,6 +139,8 @@ class Handler /** * Method for handling HTTP HEAD requests. + * + * This method should modify the instance's response member. */ protected function head() { @@ -157,6 +156,8 @@ class Handler /** * Method for handling HTTP POST requests. + * + * This method should modify the instance's response member. */ protected function post() { @@ -165,6 +166,8 @@ class Handler /** * Method for handling HTTP PUT requests. + * + * This method should modify the instance's response member. */ protected function put() { @@ -173,6 +176,8 @@ class Handler /** * Method for handling HTTP DELETE requests. + * + * This method should modify the instance's response member. */ protected function delete() { @@ -181,6 +186,8 @@ class Handler /** * Method for handling HTTP PATCH requests. + * + * This method should modify the instance's response member. */ protected function patch() { @@ -189,6 +196,8 @@ class Handler /** * Method for handling HTTP OPTION requests. + * + * This method should modify the instance's response member. */ protected function options() { diff --git a/src/pjdietz/WellRESTed/Message.php b/src/pjdietz/WellRESTed/Message.php index a7264d7..f43fbba 100644 --- a/src/pjdietz/WellRESTed/Message.php +++ b/src/pjdietz/WellRESTed/Message.php @@ -1,12 +1,20 @@ + * @copyright Copyright 2013 by PJ Dietz + * @license MIT + */ + namespace pjdietz\WellRESTed; /** * Common base class for the Request and Response classes. * - * @property string body Entity body of the message - * @property array headers Associative array of HTTP headers + * @property string body Entity body of the message + * @property-read array headers Associative array of HTTP headers + * @property string protocol The protocol, e.g. HTTP + * @property string protocolVersion The version of the protocol */ abstract class Message { @@ -51,45 +59,49 @@ abstract class Message // !Accessors /** - * @param string $name - * @return array|string - * @throws \Exception + * @param string $propertyName + * @return mixed */ - public function __get($name) + public function __get($propertyName) { - switch ($name) { - case 'body': - return $this->getBody(); - case 'headers': - return $this->getHeaders(); - case 'protocol': - return $this->getProtocol(); - case 'protocolVersion': - return $this->getProtocolVersion(); - default: - throw new \Exception('Property ' . $name . ' does not exist.'); + $method = 'get' . ucfirst($propertyName); + if (method_exists($this, $method)) { + return $this->{$method}(); } } /** - * @param string $name + * @param string $propertyName * @param $value - * @throws \Exception */ - public function __set($name, $value) + public function __set($propertyName, $value) { - switch ($name) { - case 'body': - $this->setBody($value); - return; - case 'protocol': - $this->setProtocol($value); - return; - case 'protocolVersion': - $this->setProtocolVersion($value); - return; - default: - throw new \Exception('Property ' . $name . 'does not exist or is read-only.'); + $method = 'set' . ucfirst($propertyName); + if (method_exists($this, $method)) { + $this->{$method}($value); + } + } + + /** + * @param string $propertyName + * @return mixed + */ + public function __isset($propertyName) + { + $method = 'isset' . ucfirst($propertyName); + if (method_exists($this, $method)) { + return $this->{$method}(); + } + } + + /** + * @param string $propertyName + */ + public function __unset($propertyName) + { + $method = 'unset' . ucfirst($propertyName); + if (method_exists($this, $method)) { + $this->{$method}(); } } @@ -113,6 +125,19 @@ abstract class Message $this->body = $body; } + /** + * @return bool + */ + public function issetBody() + { + return isset($this->body); + } + + public function unsetBody() + { + unset($this->body); + } + /** * Return an associative array of all set headers. * @@ -178,7 +203,7 @@ abstract class Message * @param $name * @return bool */ - public function hasHeader($name) + public function issetHeader($name) { $lowerName = strtolower($name); return isset($this->headerLookup[$lowerName]); @@ -215,6 +240,18 @@ abstract class Message } /** + * Set the protocol for the message. + * + * The value is expected to be the name of the protocol only. If the + * version is included, the version is striped and set as the + * protocolVersion property. + * + * + * $instance->protocol = 'HTTP1/1'; + * print $instance->protocol; // 'HTTP'; + * print $instance->protocolVersion; // '1.1'; + * + * * @param $protocol */ public function setProtocol($protocol) @@ -226,6 +263,19 @@ abstract class Message } } + /** + * @return bool + */ + public function issetProtocol() + { + return isset($this->protocol); + } + + public function unsetProtocol() + { + unset($this->protocol); + } + /** * @return string */ @@ -242,4 +292,16 @@ abstract class Message $this->protocolVersion = $protocolVersion; } + /** + * @return bool + */ + public function issetProtocolVersion() + { + return isset($this->protocolVersion); + } + + public function unsetProtocolVersion() + { + unset($this->protocolVersion); + } } diff --git a/src/pjdietz/WellRESTed/Request.php b/src/pjdietz/WellRESTed/Request.php index 801b5a5..52f04e4 100644 --- a/src/pjdietz/WellRESTed/Request.php +++ b/src/pjdietz/WellRESTed/Request.php @@ -1,5 +1,11 @@ + * @copyright Copyright 2013 by PJ Dietz + * @license MIT + */ + namespace pjdietz\WellRESTed; // TODO: Include port in the URI @@ -14,12 +20,12 @@ namespace pjdietz\WellRESTed; * 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 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.) + * @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.) * * @package WellRESTed */ @@ -71,59 +77,6 @@ class Request extends Message // ------------------------------------------------------------------------- // !Accessors - /** - * @param string $name - * @return array|string - * @throws \Exception - */ - public function __get($name) - { - switch ($name) { - case 'hostname': - return $this->getHostname(); - case 'method': - return $this->getMethod(); - case 'path': - return $this->getPath(); - case 'pathParts': - return $this->getPathParts(); - case 'query': - return $this->getQuery(); - case 'uri': - return $this->getUri(); - default: - return parent::__get($name); - } - } - - /** - * @param string $name - * @param mixed $value - * @throws \Exception - */ - public function __set($name, $value) - { - switch ($name) { - case 'hostname': - $this->setHostname($value); - return; - case 'method': - $this->setMethod($value); - return; - case 'path': - $this->setPath($value); - return; - case 'query': - $this->setQuery($value); - return; - case 'uri': - $this->setUri($value); - return; - default: - parent::__set($name, $value); - } - } - /** * @return string */ @@ -140,6 +93,19 @@ class Request extends Message $this->hostname = $hostname; } + /** + * @return bool + */ + public function issetHostName() + { + return isset($this->hostname); + } + + public function unsetHostname() + { + unset($this->hostname); + } + /** * @return string */ diff --git a/src/pjdietz/WellRESTed/Response.php b/src/pjdietz/WellRESTed/Response.php index cd96657..454844b 100644 --- a/src/pjdietz/WellRESTed/Response.php +++ b/src/pjdietz/WellRESTed/Response.php @@ -1,21 +1,20 @@ + * @copyright Copyright 2013 by PJ Dietz + * @license MIT + */ + namespace pjdietz\WellRESTed; -/******************************************************************************* - * Response - * +/** * A Response instance allows you to build an HTTP response and send it when * finished. * - * @package WellRESTed - * - ******************************************************************************/ - -/** * @property string reasonPhrase Text explanation of status code. * @property int statusCode HTTP status code - * @property string statusLine HTTP status line, e.g. "HTTP/1.1 200 OK" + * @property-read string statusLine HTTP status line, e.g. "HTTP/1.1 200 OK" */ class Response extends Message { @@ -59,56 +58,11 @@ class Response extends Message if (!is_null($body)) { $this->body = $body; } - - if (isset($_SERVER['SERVER_PROTOCOL'])) { - $this->protocol = $_SERVER['SERVER_PROTOCOL']; - } else { - $this->protocol = 'HTTP/1.1'; - } - } // ------------------------------------------------------------------------- // !Accessors - /** - * @param string $name - * @return array|string - * @throws \Exception - */ - public function __get($name) - { - switch ($name) { - case 'reasonPhrase': - return $this->getReasonPhrase(); - case 'statusCode': - return $this->getStatusCode(); - case 'statusLine': - return $this->getStatusLine(); - default: - return parent::__get($name); - } - } - - /** - * @param string $name - * @param mixed $value - * @throws \Exception - */ - public function __set($name, $value) - { - switch ($name) { - case 'reasonPhrase': - $this->setReasonPhrase($value); - return; - case 'statusCode': - $this->setStatusCode($value); - return; - default: - parent::__set($name, $value); - } - } - /** * Provide a new entity body for the respone. * This method also updates the content-length header based on the length @@ -152,9 +106,8 @@ class Response extends Message /** * @param int $statusCode - * @param string $reasonPhrase + * @param string|null $reasonPhrase * @throws \InvalidArgumentException - * @return void */ public function setStatusCode($statusCode, $reasonPhrase = null) { diff --git a/src/pjdietz/WellRESTed/Route.php b/src/pjdietz/WellRESTed/Route.php index 951cd92..9b71d04 100644 --- a/src/pjdietz/WellRESTed/Route.php +++ b/src/pjdietz/WellRESTed/Route.php @@ -1,14 +1,18 @@ + * @copyright Copyright 2013 by PJ Dietz + * @license MIT + */ + namespace pjdietz\WellRESTed; -/******************************************************************************* - * Route +/** + * A Route connects a URI pattern to a Handler. * * @package WellRESTed - * - ******************************************************************************/ - + */ class Route { const RE_SLUG = '[0-9a-zA-Z\-_]+'; @@ -40,6 +44,8 @@ class Route public $handler; /** + * Create a new Route + * * @param $pattern * @param $handler */ diff --git a/src/pjdietz/WellRESTed/Router.php b/src/pjdietz/WellRESTed/Router.php index fccbe67..36e4bf3 100644 --- a/src/pjdietz/WellRESTed/Router.php +++ b/src/pjdietz/WellRESTed/Router.php @@ -1,21 +1,23 @@ + * @copyright Copyright 2013 by PJ Dietz + * @license MIT + */ + namespace pjdietz\WellRESTed; -/******************************************************************************* +/** * Router * * A Router uses a table of Routes to find the appropriate Handler for a * request. - * - * @package WellRESTed - * - ******************************************************************************/ - + */ class Router { /** - * Array of \WellRESTed\Route objects + * Array of Route objects * @var array */ protected $routes; @@ -31,7 +33,7 @@ class Router /** * Append a new Route instance to the Router's route table. * - * @param $route + * @param Route $route */ public function addRoute(Route $route) {