Add page-level doc blocks to each script

Update comments
Update magic accessors
Update accessor and add islet and unset methods

src/pjdietz/WellRESTed/Exceptions/CurlException.php

@@ -1,5 +1,11 @@
 <?php
 
+/**
+ * @author PJ Dietz <pj@pjdietz.com>
+ * @copyright Copyright 2013 by PJ Dietz
+ * @license MIT
+ */
+
 namespace pjdietz\WellRESTed\Exceptions;
 
 /**

src/pjdietz/WellRESTed/Exceptions/WellrestedException.php

@@ -1,5 +1,11 @@
 <?php
 
+/**
+ * @author PJ Dietz <pj@pjdietz.com>
+ * @copyright Copyright 2013 by PJ Dietz
+ * @license MIT
+ */
+
 namespace pjdietz\WellRESTed\Exceptions;
 
 use \Exception;

src/pjdietz/WellRESTed/Handler.php

@@ -1,22 +1,20 @@
 <?php
 
+/**
+ * @author PJ Dietz <pj@pjdietz.com>
+ * @copyright Copyright 2013 by PJ Dietz
+ * @license MIT
+ */
+
 namespace pjdietz\WellRESTed;
 
-/*******************************************************************************
+/**
- * Handler
- *
  * A Handler issues a response for a given resource.
  *
- * @package WellRESTed
+ * @property-read Response response  The Response to the request
- *
- ******************************************************************************/
-
-/**
- * @property Response response  The Response to the request
  */
 class Handler
 {
-
     /**
      * The HTTP request to respond to.
      *
@@ -61,17 +59,14 @@ class Handler
     // !Accessors
 
     /**
-     * @param $name
+     * @param string $propertyName
-     * @return Response
+     * @return mixed
-     * @throws \Exception
      */
-    public function __get($name)
+    public function __get($propertyName)
     {
-        switch ($name) {
+        $method = 'get' . ucfirst($propertyName);
-            case 'response':
+        if (method_exists($this, $method)) {
-                return $this->getResponse();
+            return $this->{$method}();
-            default:
-                throw new \Exception('Property ' . $name . ' does not exist.');
         }
     }
 
@@ -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()
     {

src/pjdietz/WellRESTed/Message.php

@@ -1,12 +1,20 @@
 <?php
 
+/**
+ * @author PJ Dietz <pj@pjdietz.com>
+ * @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 string body  Entity body of the message
- * @property array headers     Associative array of HTTP headers
+ * @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
+     * @param string $propertyName
-     * @return array|string
+     * @return mixed
-     * @throws \Exception
      */
-    public function __get($name)
+    public function __get($propertyName)
     {
-        switch ($name) {
+        $method = 'get' . ucfirst($propertyName);
-            case 'body':
+        if (method_exists($this, $method)) {
-                return $this->getBody();
+            return $this->{$method}();
-            case 'headers':
-                return $this->getHeaders();
-            case 'protocol':
-                return $this->getProtocol();
-            case 'protocolVersion':
-                return $this->getProtocolVersion();
-            default:
-                throw new \Exception('Property ' . $name . ' does not exist.');
         }
     }
 
     /**
-     * @param string $name
+     * @param string $propertyName
      * @param $value
-     * @throws \Exception
      */
-    public function __set($name, $value)
+    public function __set($propertyName, $value)
     {
-        switch ($name) {
+        $method = 'set' . ucfirst($propertyName);
-            case 'body':
+        if (method_exists($this, $method)) {
-                $this->setBody($value);
+            $this->{$method}($value);
-                return;
+        }
-            case 'protocol':
+    }
-                $this->setProtocol($value);
+
-                return;
+    /**
-            case 'protocolVersion':
+     * @param string $propertyName
-                $this->setProtocolVersion($value);
+     * @return mixed
-                return;
+     */
-            default:
+    public function __isset($propertyName)
-                throw new \Exception('Property ' . $name . 'does not exist or is read-only.');
+    {
+        $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.
+     *
+     * <code>
+     * $instance->protocol = 'HTTP1/1';
+     * print $instance->protocol; // 'HTTP';
+     * print $instance->protocolVersion; // '1.1';
+     * </code>
+     *
      * @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);
+    }
 }

src/pjdietz/WellRESTed/Request.php

@@ -1,5 +1,11 @@
 <?php
 
+/**
+ * @author PJ Dietz <pj@pjdietz.com>
+ * @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 hostname  Hostname part of the URI
- * @property string method     HTTP method (GET, POST, PUT, DELETE, etc.)
+ * @property string method  HTTP method (GET, POST, PUT, DELETE, etc.)
- * @property string path       Path component of the URI for the request
+ * @property string path  Path component of the URI for the request
- * @property string pathParts  Fragments of the path, delimited by slashes
+ * @property-read string pathParts  Fragments of the path, delimited by slashes
- * @property array query       Associative array of query parameters
+ * @property array query  Associative array of query parameters
- * @property array uri         Full URI (protocol, hostname, path, etc.)
+ * @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
      */

src/pjdietz/WellRESTed/Response.php

@@ -1,21 +1,20 @@
 <?php
 
+/**
+ * @author PJ Dietz <pj@pjdietz.com>
+ * @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)
     {

src/pjdietz/WellRESTed/Route.php

@@ -1,14 +1,18 @@
 <?php
 
+/**
+ * @author PJ Dietz <pj@pjdietz.com>
+ * @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
      */

src/pjdietz/WellRESTed/Router.php

@@ -1,21 +1,23 @@
 <?php
 
+/**
+ * @author PJ Dietz <pj@pjdietz.com>
+ * @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)
     {