From a2255bebd9fc145c1c00fe0eff08a766b7115724 Mon Sep 17 00:00:00 2001
From: PJ Dietz <pjdietz@gmail.com>
Date: Wed, 5 Dec 2012 16:08:30 -0500
Subject: [PATCH] Namespace API sample. Add and update comments.

---
 samples/apisample/ApiSampleRouter.inc.php     | 12 +++++++++---
 .../apisample/data/ArticlesControler.inc.php  |  5 +++++
 .../handlers/ArticleCollectionHandler.inc.php | 15 ++++++++++++---
 .../handlers/ArticleItemHandler.inc.php       | 19 +++++++++++++++++--
 samples/apisample/index.php                   |  2 +-
 5 files changed, 44 insertions(+), 9 deletions(-)

diff --git a/samples/apisample/ApiSampleRouter.inc.php b/samples/apisample/ApiSampleRouter.inc.php
index 92660af..f321cfc 100644
--- a/samples/apisample/ApiSampleRouter.inc.php
+++ b/samples/apisample/ApiSampleRouter.inc.php
@@ -1,7 +1,12 @@
 <?php
 
+namespace apisample;
+
 require_once(dirname(__FILE__) . '/../../Router.inc.php');
 
+/**
+ * Loads and instantiates handlers based on URI.
+ */
 class ApiSampleRouter extends \wellrested\Router {
 
     public function __construct() {
@@ -9,16 +14,16 @@ class ApiSampleRouter extends \wellrested\Router {
         parent::__construct();
 
         $this->addTemplate('/articles/',
-                '\handlers\ArticleCollectionHandler',
+                'ArticleCollectionHandler',
                 'ArticleCollectionHandler.inc.php');
 
         $this->addTemplate('/articles/{id}',
-                '\handlers\ArticleItemHandler',
+                'ArticleItemHandler',
                 'ArticleItemHandler.inc.php',
                 array('id' => \wellrested\Route::RE_NUM));
 
         $this->addTemplate('/articles/{slug}',
-                '\handlers\ArticleItemHandler',
+                'ArticleItemHandler',
                 'ArticleItemHandler.inc.php',
                 array('slug' => \wellrested\Route::RE_SLUG));
 
@@ -28,6 +33,7 @@ class ApiSampleRouter extends \wellrested\Router {
 
         // Customize as needed based on your server.
         $template = '/wellrested/samples/apisample' . $template;
+        $handlerClassName = '\apisample\handlers\\' . $handlerClassName;
         $handlerFilePath = dirname(__FILE__) . '/handlers/' . $handlerFilePath;
 
         $this->addRoute(\wellrested\Route::newFromUriTemplate(
diff --git a/samples/apisample/data/ArticlesControler.inc.php b/samples/apisample/data/ArticlesControler.inc.php
index b4ce53e..c9538e1 100644
--- a/samples/apisample/data/ArticlesControler.inc.php
+++ b/samples/apisample/data/ArticlesControler.inc.php
@@ -1,5 +1,10 @@
 <?php
 
+namespace apisample\data;
+
+/**
+ * Simple class for reading and writing articles to a text file.
+ */
 class ArticlesControler {
 
     public $data;
diff --git a/samples/apisample/handlers/ArticleCollectionHandler.inc.php b/samples/apisample/handlers/ArticleCollectionHandler.inc.php
index 74a29d0..7b10310 100644
--- a/samples/apisample/handlers/ArticleCollectionHandler.inc.php
+++ b/samples/apisample/handlers/ArticleCollectionHandler.inc.php
@@ -1,16 +1,22 @@
 <?php
 
-namespace handlers;
+namespace apisample\handlers;
 
 require_once(dirname(__FILE__) . '/../../../Handler.inc.php');
 require_once(dirname(__FILE__) . '/../data/ArticlesControler.inc.php');
 
+/**
+ * Handler class for a list of articles.
+ */
 class ArticleCollectionHandler extends \wellrested\Handler {
 
+    /**
+     * Respond to a GET request.
+     */
     protected function get() {
 
         // Display the list of articles.
-        $articles = new \ArticlesControler();
+        $articles = new \apisample\data\ArticlesControler();
 
         if (isset($articles->data)) {
 
@@ -28,6 +34,9 @@ class ArticleCollectionHandler extends \wellrested\Handler {
 
     }
 
+    /**
+     * Respond to a POST request.
+     */
     protected function post() {
 
         // Read the request body, and ensure it is in the proper format.
@@ -64,7 +73,7 @@ class ArticleCollectionHandler extends \wellrested\Handler {
         }
 
         // Ensure slug is not a duplicate.
-        $articles = new \ArticlesControler();
+        $articles = new \apisample\data\ArticlesControler();
         if ($articles->getArticleBySlug($article['slug']) !== false) {
             $this->response->statusCode = 409;
             $this->response->setHeader('Content-type', 'text/plain');
diff --git a/samples/apisample/handlers/ArticleItemHandler.inc.php b/samples/apisample/handlers/ArticleItemHandler.inc.php
index 2675743..5f82ad3 100644
--- a/samples/apisample/handlers/ArticleItemHandler.inc.php
+++ b/samples/apisample/handlers/ArticleItemHandler.inc.php
@@ -1,16 +1,25 @@
 <?php
 
-namespace handlers;
+namespace apisample\handlers;
 
 require_once(dirname(__FILE__) . '/../../../Handler.inc.php');
 require_once(dirname(__FILE__) . '/../data/ArticlesControler.inc.php');
 
+/**
+ * Handler class for one specific article.
+ *
+ * When instantiated by the Router, this class should receive an id or slug
+ * argument to identify the article.
+ */
 class ArticleItemHandler extends \wellrested\Handler {
 
+    /**
+     * Respond to a GET request.
+     */
     protected function get() {
 
         // Read the list of articles.
-        $articles = new \ArticlesControler();
+        $articles = new \apisample\data\ArticlesControler();
 
         $article = false;
 
@@ -41,6 +50,9 @@ class ArticleItemHandler extends \wellrested\Handler {
 
     }
 
+    /**
+     * Respond to a PUT request.
+     */
     protected function put() {
 
         // Read the request body, and ensure it is in the proper format.
@@ -141,6 +153,9 @@ class ArticleItemHandler extends \wellrested\Handler {
 
     }
 
+    /**
+     * Respond to a DELETE request.
+     */
     protected function delete() {
 
         // Read the list of articles.
diff --git a/samples/apisample/index.php b/samples/apisample/index.php
index fcc432f..0ea501f 100644
--- a/samples/apisample/index.php
+++ b/samples/apisample/index.php
@@ -2,7 +2,7 @@
 
 require_once('ApiSampleRouter.inc.php');
 
-$router = new ApiSampleRouter();
+$router = new \apisample\ApiSampleRouter();
 $response = $router->getResponse();
 $response->respond();
 exit;