Overview ¶
Zend_Controller_Front
Zend_Controller_Front
Zend_Controller_Front
At a bare minimum, the front controller needs one or more paths todirectories containing
Note:
Default Behaviour
By default, the frontcontroller loads theErrorHandler plugin,as well as the ViewRenderer actionhelper plugin. These are to simplify error handling and viewrenderering in your controllers, respectively.
To disable theErrorHandler, perform the following at any pointprior to calling dispatch():
To disable the
//Disable the ErrorHandler plugin: $front-> setParam ( 'noErrorHandler',true ); ViewRenderer, do the following prior tocalling dispatch():
//Disable the ViewRenderer helper: $front-> setParam ( 'noViewRenderer',true );
Primary Methods ¶
The front controller has several accessors for setting up itsenvironment. However, there are three primary methods key to thefront controller's functionality:
getInstance() ¶
getInstance()
-
$front
=Zend_Controller_Front:: getInstance ( );
setControllerDirectory() and addControllerDirectory ¶
setControllerDirectory()
As some examples:
-
// Setthe default controller directory:
-
$front-> setControllerDirectory ( '../application/controllers' );
-
-
// Setseveral module directories at once:
-
'default' => '../application/controllers', -
'blog' => '../modules/blog/controllers', -
'news' => '../modules/news/controllers', -
) );
-
-
// Adda 'foo' module directory:
-
$front-> addControllerDirectory ( '../modules/foo/controllers',
'foo' );
Note: If you use
addControllerDirectory() withouta module name, it will set the directory for the default module --overwriting it if it already exists.
You can get the current settings for the controller directoryusing
addModuleDirectory() and getModuleDirectory() ¶
One aspect of the front controller is that you may
Each module should be in its own directory and mirror the directorystructure of the default module -- i.e., it should havea
addModuleDirectory()
Later, if you want to determine the path to a particular module orthe current module, you can callgetModuleDirectory(),optionally passing a module name to get that specific moduledirectory.
dispatch() ¶
dispatch(Zend_Controller_Request_Abstract $request = null,Zend_Controller_Response_Abstract $response =null)
If no request or response object are passed in,
Similarly,
The dispatch process has three distinct events:
-
Routing
-
Dispatching
-
Response
Routing takes place exactly once, using the values in the requestobject when
run() ¶
Zend_Controller_Front::run($path)
Basically,
-
//Instantiate front controller, set controller directory, anddispatch in one
-
//easy step:
-
Zend_Controller_Front:: run ( '../application/controllers' );
Environmental Accessor Methods ¶
In addition to the methods listed above, there are a number ofaccessor methods that can be used to affect the front controllerenvironment -- and thus the environment of the classes to which thefront controller delegates.
-
resetInstance()
can be used toclear all current settings. Its primary purpose is for testing, butit can also be used for instances where you wish to chain togethermultiple front controllers. -
setDefaultControllerName
() and getDefaultControllerName () letyou specify a different name to use for the default controller('index' is used otherwise) and retrieve the current value. Theyproxy to thedispatcher. -
setDefaultAction()
and getDefaultAction() letyou specify a different name to use for the default action ('index'is used otherwise) and retrieve the current value. They proxyto thedispatcher. -
setRequest()
and getRequest() letyou specify therequest class or object touse during the dispatch process and to retrieve the current object.When setting the request object, you may pass in a request classname, in which case the method will load the class file andinstantiate it. -
setRouter()
getRouter() letyou specify therouter class or object touse during the dispatch process and to retrieve the current object.When setting the router object, you may pass in a router classname, in which case the method will load the class file andinstantiate it. When retrieving the router object, it first checks to see if one ispresent, and if not, instantiates the default router (rewriterouter).
-
setBaseUrl()
and getBaseUrl() letyou specify thebase URL to strip whenrouting requests and to retrieve the current value. The value isprovided to the request object just prior to routing. -
setDispatcher()
and getDispatcher() letyou specify thedispatcher class or object touse during the dispatch process and retrieve the current object.When setting the dispatcher object, you may pass in a dispatcherclass name, in which case the method will load the class file andinstantiate it. When retrieving the dispatcher object, it first checks to see ifone is present, and if not, instantiates the defaultdispatcher.
-
setResponse()
and getResponse() letyou specify theresponse class or object touse during the dispatch process and to retrieve the current object.When setting the response object, you may pass in a response classname, in which case the method will load the class file andinstantiate it. -
registerPlugin(Zend_Controller_Plugin_Abstract $plugin, $stackIndex= null)allows you to register
pluginobjects. By setting the optional $stackIndex,you can control the order in which plugins will execute. -
unregisterPlugin($plugin)
let youunregister pluginobjects. $plugin maybe either a plugin object or a string denoting the class of pluginto unregister. -
throwExceptions($flag)
is used to turnon/off the ability to throw exceptions during the dispatch process.By default, exceptions are caught and placed in the responseobject; turning onthrowExceptions() willoverride this behaviour. For more information, read
MVCExceptions. -
returnResponse($flag)
is used to tellthe front controller whether to return the response(TRUE) from dispatch(),or if the response should be automatically emitted(FALSE). By default, the response is automaticallyemitted (by callingZend_Controller_Response_Abstract::sendResponse());turning on returnResponse() willoverride this behaviour. Reasons to return the response include a desire to check forexceptions prior to emitting the response, needing to log variousaspects of the response (such as headers), etc.
Front Controller Parameters ¶
In the introduction, we indicated that the front controller alsoacts as a registry for the various controller components. It doesso through a family of "param" methods. These methods allow you toregister arbitrary data -- objects and variables -- with the frontcontroller to be retrieved at any time in the dispatch chain. Thesevalues are passed on to the router, dispatcher, and actioncontrollers. The methods include:
-
setParam($name, $value)
allows you to seta single parameter of $name withvalue $value. -
setParams(array $params)
allows you to setmultiple parameters at once using an associative array. -
getParam($name)
allows you toretrieve a single parameter at a time, using $name asthe identifier. -
getParams()
allows you toretrieve the entire list of parameters at once. -
clearParams()
allows you toclear a single parameter (by passing a string identifier), multiplenamed parameters (by passing an array of string identifiers), orthe entire parameter stack (by passing nothing).
There are several pre-defined parameters that may be set that havespecific uses in the dispatch chain:
-
useDefaultControllerAlwa
ys is used to hintto thedispatcher to use the defaultcontroller in the default module for any request that is notdispatchable (i.e., the module, controller, and/or action do notexist). By default, this is off. See
MVCExceptions You May Encounter for more detailedinformation on using this setting. -
disableOutputBuffering
is used to hintto thedispatcher that it should notuse output buffering to capture output generated by actioncontrollers. By default, the dispatcher captures any output andappends it to the response object body content. -
noViewRenderer
is used to disablethe ViewRenderer.Set this parameter to TRUE todisable it. -
noErrorHandler
is used to disablethe ErrorHandler plugin. Set this parameter to TRUE todisable it.
Extending the Front Controller ¶
To extend the Front Controller, at the very minimum you will needto override the
-
class
My_Controller_Front extends Zend_Controller_Front -
{
-
{ -
if ( null ===self:: $_instance ) { -
self:: $_instance = new self ( ); -
} -
-
return self:: $_instance; -
} -
}
Overriding the
Typically, you will not need to subclass the front controllerunless you need to add new functionality (for instance, a pluginautoloader, or a way to specify action helper paths). Some pointswhere you may want to alter behaviour may include modifying howcontroller directories are stored, or what default router ordispatcher are used.