Zend_Controller_Router_Route_Rest - Luke Crouch

Zend_Controller_Router_Route_Rest
{zone-data}

{zone-data:proposer-list}
[luke.crouch@gmail.com|mailto:luke.crouch@gmail.com]
[Matthew Weier O'Phinney - Zend Liaison|~matthew]
{zone-data}

{zone-data:revision}
1.0 - 23 Feb 2008: Started.
1.0 - 15 May 2008: changed from Route class to full-on Router class.

{zone-data:overview}
Zend_Rest_Route is a route that uses URI to route the module & controller and HTTP request method to route to the action of a Zend_Controller_Action_Rest controller.

Zend_Rest_Controller is an abstract action controller designating the action methods to implement for use with Zend_Controller_Router_Route_Rest.

Zend_Rest_PutHandler is a controller plugin to improve PUT body handling - enables controllers to access x-www-form-urlencoded PUT bodies via getParams().
{zone-data}

{zone-data:references}
* [REST wiki|http://rest.blueoxen.net/]
* [Wikipedia REST page|http://en.wikipedia.org/wiki/Representational_State_Transfer]
* [Routing in Rails 2.0 with REST|http://darynholmes.wordpress.com/2008/05/26/beginners-tutorial-routing-in-rails-20-with-rest-part-5-of-n/]
{zone-data}

{zone-data:requirements}
* This component *will* operate as a Route class of the Rewrite Router.
* This component *will* route to Modules and Controllers based on URI tokens.
* This component *will* route to specific Actions based on HTTP request types.
* This component *will* support overloaded-POST-based routing for PUT and DELETE request types.
* This component *will* route to some special Actions based on URI tokens.
* This component *will* include an abstract Zend_Controller_Action class for implementation reference.
* This component *will* allow for designating specific REST Modules and/or Controllers
{zone-data}

{zone-data:dependencies}
* Zend_Controller
{zone-data}

{zone-data:operation}
A RESTful routing paradigm for Zend_Controller should behave as follows:
||Request method||URI||Module_Controller::action||
|GET|/product/ratings/|Product_RatingsController::indexAction()|
|GET|/product/ratings/id/:id|Product_RatingsController::getAction()|
|GET|/product/ratings/new|Product_RatingsController::newAction()|
|GET|/product/ratings/id/:id/edit|Product_RatingsController::editAction()|
|POST|/product/ratings|Product_RatingsController::postAction()|
|PUT|/product/ratings/id/:id|Product_RatingsController::putAction()|
|DELETE|/product/ratings/id/:id|Product_RatingsController::deleteAction()|
|POST|/product/ratings/id/:id
_method=PUT|Product_RatingsController::putAction()|
|POST|/product/ratings/id/:id
_method=DELETE|Product_RatingsController::deleteAction()|
{zone-data}

{zone-data:milestones}
* Milestone 1: Working prototype checked into the incubator supporting use cases #1
* Milestone 2: Unit tests exist, work, and are checked into SVN.
* Milestone 3: Initial documentation exists.
{zone-data}

{zone-data:class-list}
* Zend_Rest_Route
* Zend_Rest_Controller
* Zend_Rest_PutHandler
{zone-data}

{zone-data:use-cases}
{deck:id=Use Cases}
{card:label=Application-wide RESTful routing}
{code}
$front = Zend_Controller_Front::getInstance();
$restRoute = new Zend_Rest_Route($front);
$front->getRouter()->addRoute('default', $restRoute);
{code}
{card}
{card:label=Module-wide RESTful routing (for the Product module)}
{code}
$front = Zend_Controller_Front::getInstance();
$restRoute = new Zend_Rest_Route($front,array(),array('product'));
$front->getRouter()->addRoute('rest', $restRoute);
{code}
{card}
{card:label=Module+Controller-specific RESTful routing (for the Product_RatingsController controller)}
{code}
$front = Zend_Controller_Front::getInstance();
$restRoute = new Zend_Rest_Route($front,array(),array('product'=>array('ratings')));
$front->getRouter()->addRoute('rest', $restRoute);
{code}
{card}
{deck}
{zone-data}

{zone-data:skeletons}
{deck:id=Class Skeletons}
{card:label=Zend_Rest_Route}
{code}
<?php
/**
* Zend Framework
*
* LICENSE
*

* This source file is subject to the new BSD license that is bundled
* with this package in the file LICENSE.txt.
* It is also available through the world-wide-web at this URL:
* http://framework.zend.com/license/new-bsd
* If you did not receive a copy of the license and are unable to
* obtain it through the world-wide-web, please send an email

* to license@zend.com so we can send you a copy immediately.
*
* @package Zend_Controller
* @subpackage Router
* @copyright Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
* @version $Id: Module.php 8972 2008-03-21 18:48:44Z thomas $
* @license http://framework.zend.com/license/new-bsd New BSD License
*/

/** Zend_Controller_Router_Route_Interface */
require_once 'Zend/Controller/Router/Route/Interface.php';

/** Zend_Controller_Dispatcher_Interface */
require_once 'Zend/Controller/Dispatcher/Interface.php';

/** Zend_Controller_Request_Abstract */
require_once 'Zend/Controller/Request/Abstract.php';

/**
* Rest Route
*
* Request-aware route for RESTful modular routing
*
* @package Zend_Controller
* @subpackage Router
* @copyright Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
class Zend_Rest_Route extends Zend_Controller_Router_Route_Module
{
/**
* Specific Modules to receive RESTful routes
* @var array
*/
protected $_restfulModules = null;

/**
* Specific Modules=>Controllers to receive RESTful routes
* @var array
*/
protected $_restfulControllers = null;

/**
* Constructor
*
* @param array $defaults Defaults for map variables with keys as variable names
* @param Zend_Controller_Front $front Front Controller object
*/
public function __construct(Zend_Controller_Front $front,
array $defaults = array(),
array $responders = array())
{
$this->_defaults = $defaults;

if($responders)
$this->_parseResponders($responders);

if (isset($front)) {
$this->_request = $front->getRequest();
$this->_dispatcher = $front->getDispatcher();
}
}

/**
* Matches a user submitted request. Assigns and returns an array of variables
* on a successful match.
*
* If a request object is registered, it uses its setModuleName(),
* setControllerName(), and setActionName() accessors to set those values.
* Always returns the values as an array.
*
* @param Zend_Controller_Request_Http $request Request used to match against this routing ruleset
* @return array An array of assigned values or a false on a mismatch
*/
public function match($request)
{
$this->_setRequestKeys();

$path = $request->getPathInfo();
$values = array();
$params = array();
$path = trim($path, self::URI_DELIMITER);

if ($path != '') {

$path = explode(self::URI_DELIMITER, $path);

// Determine Module
$moduleName = $this->_defaults[$this->_moduleKey];
if ($this->_dispatcher && $this->_dispatcher->isValidModule($path[0])) {
$moduleName = $path[0];
if ($this->_checkRestfulModule($moduleName)) {
$values[$this->_moduleKey] = array_shift($path);
$this->_moduleValid = true;
}
}

// Determine Controller
$controllerName = $this->_defaults[$this->_controllerKey];
if (count($path) && !empty($path[0])) {
if ($this->_checkRestfulController($moduleName, $path[0])) {
$controllerName = $path[0];
$values[$this->_controllerKey] = array_shift($path);
$values[$this->_actionKey] = 'get';
} else {
// If Controller in URI is not found to be a RESTful
// Controller, return false to fall back to other routes
return false;
}
}

// Check for leading "special get" URI's
$specialGetTarget = false;
if (count($path) && array_search($path[0], array('index', 'new')) > -1) {
$specialGetTarget = array_shift($path);
}

// Digest URI params
if ($numSegs = count($path)) {
for ($i = 0; $i < $numSegs; $i = $i + 2) {
$key = urldecode($path[$i]);
$val = isset($path[$i + 1]) ? urldecode($path[$i + 1]) : null;
$params[$key] = $val;
}
}

// Check for trailing "special get" URI
if (array_key_exists('edit', $params))
$specialGetTarget = 'edit';

// Determine Action
$requestMethod = strtolower($request->getMethod());
if ($requestMethod != 'get') {
if ($request->getParam('_method')) {
$values[$this->_actionKey] = strtolower($request->getParam('_method'));
} else {
$values[$this->_actionKey] = $requestMethod;
}
} elseif ($specialGetTarget) {
$values[$this->_actionKey] = $specialGetTarget;
}

}
$this->_values = $values + $params;

return $this->_values + $this->_defaults;
}

/**
* Assembles user submitted parameters forming a URL path defined by this route
*
* @param array $data An array of variable and value pairs used as parameters
* @param bool $reset Weither to reset the current params
* @return string Route path with user submitted parameters
*/
public function assemble($data = array(), $reset = false, $encode = true)
{
if (!$this->_keysSet) {
$this->_setRequestKeys();
}

$params = (!$reset) ? $this->_values : array();

foreach ($data as $key => $value) {
if ($value !== null) {
$params[$key] = $value;
} elseif (isset($params[$key])) {
unset($params[$key]);
}
}

$params += $this->_defaults;

$url = '';

if ($this->_moduleValid || array_key_exists($this->_moduleKey, $data)) {
if ($params[$this->_moduleKey] != $this->_defaults[$this->_moduleKey]) {
$module = $params[$this->_moduleKey];
}
}
unset($params[$this->_moduleKey]);

$controller = $params[$this->_controllerKey];
unset($params[$this->_controllerKey]);

foreach ($params as $key => $value) {
$url .= '/' . $key;
$url .= '/' . $value;
}

if (!empty($url) || $controller !== $this->_defaults[$this->_controllerKey]) {
$url = '/' . $controller . $url;
}

if (isset($module)) {
$url = '/' . $module . $url;
}

return ltrim($url, self::URI_DELIMITER);
}

/**
* Tells Rewrite Router which version this Route is
*
* @return int Route "version"
*/
public function getVersion()
{
return 2;
}

private function _parseResponders($responders)
{
$modulesOnly = true;
foreach ($responders as $responder){
if(is_array($responder))
$modulesOnly = false;
}
if ($modulesOnly){
$this->_restfulModules = $responders;
} else {
$this->_restfulControllers = $responders;
}
}

private function _checkRestfulModule($moduleName)
{
if ($this->_allRestful())
return true;
if ($this->_fullRestfulModule($moduleName))
return true;
if ($this->_restfulControllers && array_key_exists($moduleName, $this->_restfulControllers))
return true;
return false;
}

private function _checkRestfulController($moduleName, $controllerName)
{
if ($this->_allRestful())
return true;
if ($this->_fullRestfulModule($moduleName))
return true;
if ($this->_restfulControllers && array_search($controllerName, $this->_restfulControllers[$moduleName]) !== false)
return true;
return false;
}

private function _allRestful()
{
return (!$this->_restfulModules && !$this->_restfulControllers);
}

private function _fullRestfulModule($moduleName)
{
return ($this->_restfulModules && array_search($moduleName, $this->_restfulModules) !== false);
}

}
{code}
{card}
{card:label=Zend_Rest_Controller}
{code}
abstract class Zend_Rest_Controller extends Zend_Controller_Action
{
public function indexAction()
{
// select all from resource table;
// put the resources onto view;
}

public function getAction()
{
// retrieve resource where id = URI param;
// put resource onto view
}

public function editAction()
{
// retrieve resource where id = URI param;
// put resource onto view
// edit template shows form for editing the resource
}

public function newAction()
{
// new template shows form for submitting new resource
}

public function postAction()
{
// create new resource with POST values;
// persist the resource
}

public function putAction()
{
// retrieve resource where id = URI param;
// update resource with PUT values;
// persist the updated resource;
}

public function deleteAction()
{
// delete resource where id = URI param;
}
}
{code}
{card}
{card:label=Zend_Rest_PutHandler}
{code}
<?php
class Zend_Rest_PutHandler extends Zend_Controller_Plugin_Abstract
{
public function preDispatch(Zend_Controller_Request_Abstract $request)
{
if ($this->_request->isPut()){
$putParams = array();
parse_str($this->_request->getRawBody(), $putParams);
$request->setParams($putParams);
}
}
}
{code}
{card}