Zend Framework: Zend_Controller_Router_Route_Rest Component Proposal

Proposed Component Name	Zend_Controller_Router_Route_Rest
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Controller_Router_Route_Rest
Proposers	luke.crouch@gmail.com
Revision	1.0 - 23 February 2008: Started. 1.0 - 15 May 2008: changed from Route class to full-on Router class. 1.0 - 15 May 2008: changed back to Route class (wiki revision: 24)

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()

6. Milestones / Tasks

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.

7. Class Index

Zend_Controller_Router_Route_Rest

8. Use Cases

UC-01

$front = Zend_Controller_Front::getInstance();
$front->getRouter()->addRoute(new Zend_Controller_Router_Route_Rest());

class Product_RatingsController extends Zend_Controller_Action
{
   public function indexAction()
   {
      // select all from ratings table;
      // put the list/index of ratings onto view;
   }

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

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

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

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

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

   public function deleteAction()
   {
      // delete rating object where id = URI param;
   }
}

9. Class Skeletons

<?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
 *
 * Default route for module functionality
 *
 * @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_Controller_Router_Route_Rest extends Zend_Controller_Router_Route_Module 
{
    /**
     * Matches a user submitted path. 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 string $path Path used to match against this routing map
     * @return array An array of assigned values or a false on a mismatch
     */
    public function match($path, $request)
    {
        $this->_setRequestKeys();

        $values = array();
        $params = array();
        $path   = trim($path, self::URI_DELIMITER);

        if ($path != '') {

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

            if ($this->_dispatcher && $this->_dispatcher->isValidModule($path[0])) {
                $values[$this->_moduleKey] = array_shift($path);
                $this->_moduleValid = true;
            }

            if (count($path) && !empty($path[0])) {
                $values[$this->_controllerKey] = array_shift($path);
            }

			// find action from http request method
            $requestMethod = strtolower($request->getMethod());
			$requestUri = $request->getRequestUri();
            
			// strip format flag off the end if present - only viewrenderer uses that
			$formatTokenPos = strpos($requestUri, '.');
			if($formatTokenPos !== false ){
				$requestUri = substr($requestUri, 0, $formatTokenPos);
			}
			
			$requestUriLen = strlen($requestUri);
			
			$target = 'get';
			if($requestMethod != 'get'){
				$target = strtolower($requestMethod);
			} elseif ((strrpos($requestUri, '/') == ($requestUriLen-1))) {
				$target = 'index';
			} elseif (strrpos($requestUri, 'new') == ($requestUriLen-3)){
				$target = 'new';
			} elseif (strrpos($requestUri, 'edit') == ($requestUriLen-4)){
				$target = 'edit';
			}
			$values[$this->_actionKey] = $target;
            
            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;
                }
            }
        }

        $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)
    {
        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);
    }
}

Page Operations

Browse Space

Zend_Controller_Router_Route_Rest - Luke Crouch

Labels

Zend Framework: Zend_Controller_Router_Route_Rest Component Proposal

Table of Contents

1. Overview

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

4. Dependencies on Other Framework Components

5. Theory of Operation

6. Milestones / Tasks

7. Class Index

8. Use Cases

9. Class Skeletons