First iteration of REST controller refactoring. RESTful controllers that refer to collections should now have plural names and there should be only one controller per resource. Updated existing classes that implement REST_Controller. The routing now works like this:

GET    /controller    -> controller::_index()
POST   /controller    -> controller::_create()
GET    /controller/id -> controller::_show()
PUT    /controller/id -> controller::_update()
DELETE /controller/id -> controller::_delete()
GET    /form/edit/controller/resource_id -> controller::_form()
GET    /form/add/controller/data         -> controller::_form()

4 files changed, 82 insertions, 46 deletions

diff --git a/core/controllers/album.php b/core/controllers/album.php
index a5853fa7..82652d88 100644
--- a/core/controllers/album.php
+++ b/core/controllers/album.php
@@ -20,16 +20,9 @@
 class Album_Controller extends Item_Controller {
 
   /**
-   *  @see Rest_Controller::_form($resource)
+   *  @see Rest_Controller::_show($resource, $output_format)
    */
-  public function _form($comment) {
-    throw new Exception("@todo Album_Controller::_form NOT IMPLEMENTED");
-  }
-
-  /**
-   *  @see Rest_Controller::_get($resource, $output_format)
-   */
-  public function _get($item, $output_format) {
+  public function _show($item, $output_format) {
     // @todo: these need to be pulled from the database
     $theme_name = "default";
     $page_size = 9;
diff --git a/core/controllers/item.php b/core/controllers/item.php
index 70af9d95..7ee3674b 100644
--- a/core/controllers/item.php
+++ b/core/controllers/item.php
@@ -21,20 +21,27 @@ class Item_Controller extends REST_Controller {
   protected $resource_type = "item";
 
   /**
+   *  @see Rest_Controller::_index($query)
+   */
+  public function _index($query) {
+    throw new Exception("@todo Item_Controller::_index NOT IMPLEMENTED");
+  }
+
+  /**
    *  @see Rest_Controller::_form($resource)
    */
-  public function _form($item) {
+  public function _form($item, $form_type) {
     throw new Exception("@todo Comment_Controller::_form NOT IMPLEMENTED");
   }
 
-  public function _get($item, $format) {
+  public function _show($item, $format) {
     // Redirect to the more specific resource type, since it will render
     // differently.  We could also just delegate here, but it feels more appropriate
     // to have a single canonical resource mapping.
     return url::redirect("{$item->type}/$item->id");
   }
 
-  public function _put($item) {
+  public function _update($item) {
     // @todo Productionize this code
     // 1) Add security checks
     // 2) Support owner_ids properly
@@ -92,7 +99,7 @@ class Item_Controller extends REST_Controller {
     url::redirect("{$parent->type}/{$parent->id}");
   }
 
-  public function _post($item) {
+  public function _create($item) {
     // @todo Productionize this
     // 1) Figure out how to do the right validation here.  Validate the form input and apply it to
     //    the model as appropriate.
diff --git a/core/controllers/photo.php b/core/controllers/photo.php
index 819af133..d6d37f98 100644
--- a/core/controllers/photo.php
+++ b/core/controllers/photo.php
@@ -20,16 +20,9 @@
 class Photo_Controller extends Item_Controller {
 
   /**
-   *  @see Rest_Controller::_form($resource)
+   *  @see Rest_Controller::_show($resource, $output_format)
    */
-  public function _form($comment) {
-    throw new Exception("@todo Comment_Controller::_form NOT IMPLEMENTED");
-  }
-
-  /**
-   *  @see Rest_Controller::_get($resource, $output_format)
-   */
-  public function _get($item, $output_format) {
+  public function _show($item, $output_format) {
     $template = new View("page.html");
 
     // @todo: this needs to be data-driven
diff --git a/core/controllers/rest.php b/core/controllers/rest.php
index 3b630f2d..b2097aaf 100644
--- a/core/controllers/rest.php
+++ b/core/controllers/rest.php
@@ -24,16 +24,20 @@
  * class Comment_Controller extends REST_Controller {
  *   protected $resource_type = "comment";  // this tells REST which model to use
  *
- *   public function _get(ORM $comment, $output_format) {
+ *   public function _index($query) {
+ *     // Handle GET request to controller root
+ *   }
+ *
+ *   public function _show(ORM $comment, $output_format) {
  *     // Handle GET request
  *   }
  *
- *   public function _put(ORM $comment, $output_format) {
+ *   public function _update(ORM $comment, $output_format) {
  *     // Handle PUT request
  *   }
  *
- *   public function _post(ORM $comment, $output_format) {
- *     // Handle POST request
+ *   public function _create(ORM $comment, $output_format) {
+ *     // Handle POST request to controller root
  *   }
  *
  *   public function _delete(ORM $comment, $output_format) {
@@ -45,7 +49,7 @@
  *   }
  * }
  *
- * A request to http://example.com/gallery3/comment/3 will result in a call to
+ * A request to http://example.com/gallery3/comments/3 will result in a call to
  * REST_Controller::dispatch(3) which will load up the comment associated with id 3.  If there's
  * no such comment, it returns a 404.  Otherwise, it will then delegate to
  * Comment_Controller::get() with the ORM instance as an argument.
@@ -60,7 +64,7 @@ abstract class REST_Controller extends Controller {
 
     // @todo this needs security checks
     $resource = ORM::factory($this->resource_type, $id);
-    if (!$resource->loaded) {
+    if (!$resource->loaded && !$this->request_method() == "post") {
       return Kohana::show_404();
     }
     /**
@@ -68,8 +72,8 @@ abstract class REST_Controller extends Controller {
      * PUT/DELETE through POST.
      */
     $output_format = $this->input->get("_format", $this->input->post("_format", "html"));
-    if (request::method() == "get") {
-      $this->_get($resource, $output_format);
+    if ($this->request_method() == "get") {
+      $this->_show($resource, $output_format);
 
       if (Session::instance()->get("use_profiler", false)) {
         $profiler = new Profiler();
@@ -78,49 +82,88 @@ abstract class REST_Controller extends Controller {
       return;
     }
 
-    switch ($this->input->post("_method", $this->input->get("_method"))) {
+    switch ($this->request_method()) {
     case "put":
-      return $this->_put($resource);
+      return $this->_update($resource);
 
     case "delete":
       return $this->_delete($resource);
 
-    default:
-      return $this->_post($resource);
+    case "post":
+      return $this->_create($resource);
     }
   }
 
-  public function form($id) {
+  // @todo Get rid of $form_type, move to add_form() and edit_form().
+  public function form($data, $form_type) {
     if ($this->resource_type == null) {
       throw new Exception("@todo ERROR_MISSING_RESOURCE_TYPE");
     }
 
     // @todo this needs security checks
-    $resource = ORM::factory($this->resource_type, $id);
-    if (!$resource->loaded) {
-      return Kohana::show_404();
+    if ($form_type == "edit") {
+      /* We're editing an existing item, load it from the database. */
+      $resource = ORM::factory($this->resource_type, $data);
+      if (!$resource->loaded) {
+        return Kohana::show_404();
+      }
+
+      return $this->_form($resource, $form_type);
+    } else {
+      /* We're adding a new item, pass along any additional parameters. */
+      return $this->_form($data, $form_type);
     }
+  }
 
-    return $this->_form($resource);
+  public function index($query_string=null) {
+    // @todo Convert query string to an array and pass it along to _index()
+    if (request::method() == "post") {
+      return $this->dispatch(null);
+    }
+    return $this->_index(array());
   }
 
   /**
-   * Perform a GET request on this resource
+   * Return HTTP request method taking into consideration PUT and DELETE tunneling through POST.
+   * @todo Move this to a MY_request helper?
+   * @return string HTTP request method
+   */
+  protected function request_method() {
+    if (request::method() == "get") {
+      return "get";
+    } else {
+      switch ($this->input->post("_method", $this->input->get("_method"))) {
+      case "put":    return "put";
+      case "delete": return "delete";
+      default:       return "post";
+      }
+    }
+  }
+
+  /**
+   * Perform a GET request on the controller root
+   * (e.g. http://www.example.com/gallery3/comments)
+   * @param array $query name-value pairs from the query string, if any
+   */
+  abstract public function _index($query);
+
+  /**
+   * Perform a POST request on this resource
    * @param ORM $resource the instance of this resource type
    */
-  abstract public function _get($resource, $output_format);
+  abstract public function _create($resource);
 
   /**
-   * Perform a PUT request on this resource
+   * Perform a GET request on this resource
    * @param ORM $resource the instance of this resource type
    */
-  abstract public function _put($resource);
+  abstract public function _show($resource, $output_format);
 
   /**
-   * Perform a POST request on this resource
+   * Perform a PUT request on this resource
    * @param ORM $resource the instance of this resource type
    */
-  abstract public function _post($resource);
+  abstract public function _update($resource);
 
   /**
    * Perform a DELETE request on this resource
@@ -132,5 +175,5 @@ abstract class REST_Controller extends Controller {
    * Present a form for adding a new resource
    * @param ORM $resource the resource container for instances of this resource type
    */
-  abstract public function _form($resource);
+  abstract public function _form($resource, $form_type);
 }