The Dispatcher

Overview

Dispatching is the process of taking the request object, Zend_Controller_Request_Abstract, extracting the module name, controller name, action name, and optional parameters contained in it, and then instantiating a controller and calling an action of that controller. If any of the module, controller, or action are not found, it will use default values for them. Zend_Controller_Dispatcher_Standard specifies index for each of the controller and action defaults and default for the module default value, but allows the developer to change the default values for each using the setDefaultController(), setDefaultAction(), and setDefaultModule() methods, respectively.

Note: Default Module
When creating modular applications, you may find that you want your default module namespaced as well (the default configuration is that the default module is not namespaced). As of 1.5.0, you can now do so by specifying the prefixDefaultModule as TRUE in either the front controller or your dispatcher:

  1. // In your front controller:
  2. $front->setParam('prefixDefaultModule', true);
  3.  
  4. // In your dispatcher:
  5. $dispatcher->setParam('prefixDefaultModule', true);
This allows you to re-purpose an existing module to be the default module for an application.

Dispatching happens in a loop in the front controller. Before dispatching occurs, the front controller routes the request to find user specified values for the module, controller, action, and optional parameters. It then enters a dispatch loop, dispatching the request.

At the beginning of each iteration, it sets a flag in the request object indicating that the action has been dispatched. If an action or pre or postDispatch plugin resets that flag, the dispatch loop will continue and attempt to dispatch the new request. By changing the controller and/or action in the request and resetting the dispatched flag, the developer may define a chain of requests to perform.

The action controller method that controls such dispatching is _forward(); call this method from any of the preDispatch(), postDispatch() or action methods, providing an action, controller, module, and optionally any additional parameters you may wish to send to the new action:

  1. public function fooAction()
  2. {
  3.     // forward to another action in the current controller and module:
  4.     $this->_forward('bar', null, null, array('baz' => 'bogus'));
  5. }
  6.  
  7. public function barAction()
  8. {
  9.     // forward to an action in another controller:
  10.     // FooController::bazAction(),
  11.     // in the current module:
  12.     $this->_forward('baz', 'foo', null, array('baz' => 'bogus'));
  13. }
  14.  
  15. public function bazAction()
  16. {
  17.     // forward to an action in another controller in another module,
  18.     // Foo_BarController::bazAction():
  19.     $this->_forward('baz', 'bar', 'foo', array('baz' => 'bogus'));
  20. }

Subclassing the Dispatcher

Zend_Controller_Front will first call the router to determine the first action in the request. It then enters a dispatch loop, which calls on the dispatcher to dispatch the action.

The dispatcher needs a variety of data in order to do its work - it needs to know how to format controller and action names, where to look for controller class files, whether or not a provided module name is valid, and an API for determining if a given request is even dispatchable based on the other information available.

Zend_Controller_Dispatcher_Interface defines the following methods as required for any dispatcher implementation:

  1. interface Zend_Controller_Dispatcher_Interface
  2. {
  3.     /**
  4.      * Format a string into a controller class name.
  5.      *
  6.      * @param string $unformatted
  7.      * @return string
  8.      */
  9.     public function formatControllerName($unformatted);
  10.  
  11.     /**
  12.      * Format a string into an action method name.
  13.      *
  14.      * @param string $unformatted
  15.      * @return string
  16.      */
  17.     public function formatActionName($unformatted);
  18.  
  19.     /**
  20.      * Determine if a request is dispatchable
  21.      *
  22.      * @param  Zend_Controller_Request_Abstract $request
  23.      * @return boolean
  24.      */
  25.     public function isDispatchable(
  26.         Zend_Controller_Request_Abstract $request
  27.     );
  28.  
  29.     /**
  30.      * Set a user parameter (via front controller, or for local use)
  31.      *
  32.      * @param string $name
  33.      * @param mixed $value
  34.      * @return Zend_Controller_Dispatcher_Interface
  35.      */
  36.     public function setParam($name, $value);
  37.  
  38.     /**
  39.      * Set an array of user parameters
  40.      *
  41.      * @param array $params
  42.      * @return Zend_Controller_Dispatcher_Interface
  43.      */
  44.     public function setParams(array $params);
  45.  
  46.     /**
  47.      * Retrieve a single user parameter
  48.      *
  49.      * @param string $name
  50.      * @return mixed
  51.      */
  52.     public function getParam($name);
  53.  
  54.     /**
  55.      * Retrieve all user parameters
  56.      *
  57.      * @return array
  58.      */
  59.     public function getParams();
  60.  
  61.     /**
  62.      * Clear the user parameter stack, or a single user parameter
  63.      *
  64.      * @param null|string|array single key or array of keys for
  65.      *        params to clear
  66.      * @return Zend_Controller_Dispatcher_Interface
  67.      */
  68.     public function clearParams($name = null);
  69.  
  70.     /**
  71.      * Set the response object to use, if any
  72.      *
  73.      * @param Zend_Controller_Response_Abstract|null $response
  74.      * @return void
  75.      */
  76.     public function setResponse(
  77.         Zend_Controller_Response_Abstract $response = null
  78.     );
  79.  
  80.     /**
  81.      * Retrieve the response object, if any
  82.      *
  83.      * @return Zend_Controller_Response_Abstract|null
  84.      */
  85.     public function getResponse();
  86.  
  87.     /**
  88.      * Add a controller directory to the controller directory stack
  89.      *
  90.      * @param string $path
  91.      * @param string $args
  92.      * @return Zend_Controller_Dispatcher_Interface
  93.      */
  94.     public function addControllerDirectory($path, $args = null);
  95.  
  96.     /**
  97.      * Set the directory (or directories) where controller files are
  98.      * stored
  99.      *
  100.      * @param string|array $dir
  101.      * @return Zend_Controller_Dispatcher_Interface
  102.      */
  103.     public function setControllerDirectory($path);
  104.  
  105.     /**
  106.      * Return the currently set directory(ies) for controller file
  107.      * lookup
  108.      *
  109.      * @return array
  110.      */
  111.     public function getControllerDirectory();
  112.  
  113.     /**
  114.      * Dispatch a request to a (module/)controller/action.
  115.      *
  116.      * @param  Zend_Controller_Request_Abstract $request
  117.      * @param  Zend_Controller_Response_Abstract $response
  118.      * @return Zend_Controller_Request_Abstract|boolean
  119.      */
  120.     public function dispatch(
  121.         Zend_Controller_Request_Abstract $request,
  122.         Zend_Controller_Response_Abstract $response
  123.     );
  124.  
  125.     /**
  126.      * Whether or not a given module is valid
  127.      *
  128.      * @param string $module
  129.      * @return boolean
  130.      */
  131.     public function isValidModule($module);
  132.  
  133.     /**
  134.      * Retrieve the default module name
  135.      *
  136.      * @return string
  137.      */
  138.     public function getDefaultModule();
  139.  
  140.     /**
  141.      * Retrieve the default controller name
  142.      *
  143.      * @return string
  144.      */
  145.     public function getDefaultControllerName();
  146.  
  147.     /**
  148.      * Retrieve the default action
  149.      *
  150.      * @return string
  151.      */
  152.     public function getDefaultAction();
  153. }

In most cases, however, you should simply extend the abstract class Zend_Controller_Dispatcher_Abstract, in which each of these have already been defined, or Zend_Controller_Dispatcher_Standard to modify functionality of the standard dispatcher.

Possible reasons to subclass the dispatcher include a desire to use a different class or method naming schema in your action controllers, or a desire to use a different dispatching paradigm such as dispatching to action files under controller directories (instead of dispatching to class methods).

blog comments powered by Disqus