Resauce

Resauce copied to clipboard

h1. "Resauce Framework":http://github.com/mikekelly/Resauce

Resauce is a small extension to Zend Framework. It gives you a lightweight framework for building RESTful HTTP interfaces with PHP.

h2. Introduction

The main idea is to treat each controller as a Resource; i.e. a controller is responsible for one resource. This is distinct from other solutions (such as the REST components included in ZF itself) where a controller is responsible for both collection and item resources.

Example Routes:

'/blog' >> BlogController

'/blog/:post' >> BlogPostController

'/blog/:post/comments' >> BlogPostCommentsController

A route in a Resauce application simply maps a URI pattern to a Resauce controller - no controller action should ever be specified in a route. Instead - controller actions are 'routed' according to the HTTP method of a given request.

i.e.

• GET >> getAction()
• PUT >> putAction()
• PATCH >> patchAction()
• POST >> postAction()
• LINK >> linkAction()
• UNLINK >> unlinkAction()
• DELETE >> deleteAction()
• HEAD >> headAction()
• OPTIONS >> optionsAction()

If a request is routed to a resauce controller which does not have an action implemented for the given HTTP method, then the Resauce will automatically respond with a 405 Method Not Allowed response code.

h2. So what?

The Resauce approach to MVC provides much more flexibility over how resources can be exposed than other alternatives - you have complete control of URI patterns and each resource's HTTP methods.

REST is not collection/item CRUD over HTTP, frameworks that don't agree with this are needlessly restricting and/or confusing developers; when the only (debatable) 'benefit' is that collection and item resources can be handled by one controller and one route.

"For every complex problem, there is a solution that is simple, neat, and wrong." - H. L. Mencken

h2. Example Usage

Configure routing for your interface by creating an _initRoutes function in your Resauce Bootstrap.

application/Bootstrap.php:

addResauceRoutes(array(
      'blog' => 'blog',
      'blog/:post' => 'blog-post',
      'blog/:post/comments' => 'blog-post-comments'
    ));
  }
}

Then create the controllers in the controller directory, with Actions for HTTP methods you want the URI to support:

e.g. application/controllers/BlogController.php

For the routes in the example Boostrap above - you would, obviously, need to create the other controllers:

BlogPostController.php BlogPostCommentsController.php