documentation/manual/en/module_specs/Zend_Controller-Basics.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.controller.basics">
   4     <title>Zend_Controller Basics</title>
   5
   6     <para>
   7         The <classname>Zend_Controller</classname> system is designed to be
   8         lightweight, modular, and extensible. It is a minimalist design to
   9         permit flexibility and some freedom to users while providing enough
  10         structure so that systems built around <classname>Zend_Controller</classname>
  11         share some common conventions and similar code layout.
  12     </para>
  13
  14     <para>
  15         The following diagram depicts the workflow, and the narrative following
  16         describes in detail the interactions:
  17     </para>
  18
  19     <para>
  20         <inlinegraphic width="483" scale="100" align="center" valign="middle"
  21             fileref="figures/zend.controller.basics.png" format="PNG" />
  22     </para>
  23
  24     <para>
  25         The <classname>Zend_Controller</classname> workflow is implemented by several
  26         components. While it is not necessary to completely understand the
  27         underpinnings of all of these components to use the system, having a
  28         working knowledge of the process is helpful.
  29     </para>
  30
  31     <itemizedlist>
  32         <listitem>
  33             <para>
  34                 <classname>Zend_Controller_Front</classname> orchestrates the entire
  35                 workflow of the <classname>Zend_Controller</classname> system. It is
  36                 an interpretation of the FrontController pattern.
  37                 <classname>Zend_Controller_Front</classname> processes all requests
  38                 received by the server and is ultimately responsible for
  39                 delegating requests to ActionControllers
  40                 (<classname>Zend_Controller_Action</classname>).
  41             </para>
  42         </listitem>
  43
  44         <listitem>
  45             <para>
  46                 <classname>Zend_Controller_Request_Abstract</classname> (often
  47                 referred to as the <emphasis>Request Object</emphasis>) represents
  48                 the request environment and provides methods for setting and
  49                 retrieving the controller and action names and any request
  50                 parameters. Additionally it keeps track of whether or not
  51                 the action it contains has been dispatched by
  52                 <classname>Zend_Controller_Dispatcher</classname>. Extensions to the
  53                 abstract request object can be used to encapsulate the
  54                 entire request environment, allowing routers to pull
  55                 information from the request environment in order to set the
  56                 controller and action names.
  57             </para>
  58
  59             <para>
  60                 By default, <classname>Zend_Controller_Request_Http</classname> is
  61                 used, which provides access to the entire <acronym>HTTP</acronym> request
  62                 environment.
  63             </para>
  64         </listitem>
  65
  66         <listitem>
  67             <para>
  68                 <classname>Zend_Controller_Router_Interface</classname> is used to
  69                 define routers. Routing is the process of examining the
  70                 request environment to determine which controller, and
  71                 action of that controller, should receive the request. This
  72                 controller, action, and optional parameters are then set in
  73                 the request object to be processed by
  74                 <classname>Zend_Controller_Dispatcher_Standard</classname>. Routing
  75                 occurs only once: when the request is initially received and
  76                 before the first controller is dispatched.
  77             </para>
  78
  79             <para>
  80                 The default router,
  81                 <classname>Zend_Controller_Router_Rewrite</classname>, takes a
  82                 <acronym>URI</acronym> endpoint as specified in
  83                 <classname>Zend_Controller_Request_Http</classname> and decomposes it
  84                 into a controller, action, and parameters based on the path information
  85                 in the <acronym>URL</acronym>. As an example, the <acronym>URL</acronym>
  86                 <filename>http://localhost/foo/bar/key/value</filename> would be
  87                 decoded to use the <emphasis>foo</emphasis> controller,
  88                 <emphasis>bar</emphasis> action, and specify a parameter
  89                 <emphasis>key</emphasis> with a value of <emphasis>value</emphasis>.
  90             </para>
  91
  92             <para>
  93                 <classname>Zend_Controller_Router_Rewrite</classname> can also be used
  94                 to match arbitrary paths; see <link
  95                     linkend="zend.controller.router">the router documentation</link>
  96                 for more information.
  97             </para>
  98         </listitem>
  99
 100         <listitem>
 101             <para>
 102                 <classname>Zend_Controller_Dispatcher_Interface</classname> is used to
 103                 define dispatchers. Dispatching is the process of pulling
 104                 the controller and action from the request object and
 105                 mapping them to a controller file (or class) and action method in
 106                 the controller class. If the controller or action do not
 107                 exist, it handles determining default controllers and
 108                 actions to dispatch.
 109             </para>
 110
 111             <para>
 112                 The actual dispatching process consists of instantiating the
 113                 controller class and calling the action method in that
 114                 class. Unlike routing, which occurs only once, dispatching
 115                 occurs in a loop. If the request object's dispatched status
 116                 is reset at any point, the loop will be repeated, calling
 117                 whatever action is currently set in the request object. The
 118                 first time the loop finishes with the request object's
 119                 dispatched status set (<type>Boolean</type> <constant>TRUE</constant>),
 120                 it will finish processing.
 121             </para>
 122
 123             <para>
 124                 The default dispatcher is
 125                 <classname>Zend_Controller_Dispatcher_Standard</classname>. It defines
 126                 controllers as MixedCasedClasses ending in the word
 127                 Controller, and action methods as camelCasedMethods ending
 128                 in the word Action:
 129                 <methodname>FooController::barAction()</methodname>. In this case, the
 130                 controller would be referred to as <emphasis>foo</emphasis> and
 131                 the action as <emphasis>bar</emphasis>.
 132             </para>
 133
 134             <note>
 135                 <title>Case Naming Conventions</title>
 136
 137                 <para>
 138                     Since humans are notoriously inconsistent at
 139                     maintaining case sensitivity when typing links, Zend
 140                     Framework actually normalizes path information to
 141                     lowercase. This, of course, will affect how you name
 142                     your controller and actions... or refer to them in
 143                     links.
 144                 </para>
 145
 146                 <para>
 147                     If you wish to have your controller class or action
 148                     method name have multiple MixedCasedWords or
 149                     camelCasedWords, you will need to separate those words
 150                     on the url with either a '-' or '.' (though you can
 151                     configure the character used).
 152                 </para>
 153
 154                 <para>
 155                     As an example, if you were going to the action in
 156                     <methodname>FooBarController::bazBatAction()</methodname>, you'd
 157                     refer to it on the url as <filename>/foo-bar/baz-bat</filename>
 158                     or <filename>/foo.bar/baz.bat</filename>.
 159                 </para>
 160             </note>
 161         </listitem>
 162
 163         <listitem>
 164             <para>
 165                 <classname>Zend_Controller_Action</classname> is the base action
 166                 controller component. Each controller is a single class
 167                 that extends the <classname>Zend_Controller_Action</classname> class
 168                 and should contain one or more action methods.
 169             </para>
 170         </listitem>
 171
 172         <listitem>
 173             <para>
 174                 <classname>Zend_Controller_Response_Abstract</classname> defines a
 175                 base response class used to collect and return responses
 176                 from the action controllers. It collects both headers and
 177                 body content.
 178             </para>
 179
 180             <para>
 181                 The default response class is
 182                 <classname>Zend_Controller_Response_Http</classname>, which is
 183                 suitable for use in an <acronym>HTTP</acronym> environment.
 184             </para>
 185         </listitem>
 186     </itemizedlist>
 187
 188     <para>
 189         The workflow of <classname>Zend_Controller</classname> is relatively simple. A
 190         request is received by <classname>Zend_Controller_Front</classname>, which in turn
 191         calls <classname>Zend_Controller_Router_Rewrite</classname> to determine which
 192         controller (and action in that controller) to dispatch.
 193         <classname>Zend_Controller_Router_Rewrite</classname> decomposes the <acronym>URI</acronym>
 194         in order to set the controller and action names in the request.
 195         <classname>Zend_Controller_Front</classname> then enters a dispatch loop. It
 196         calls <classname>Zend_Controller_Dispatcher_Standard</classname>, passing it the
 197         request, to dispatch to the controller and action specified in the
 198         request (or use defaults). After the controller has finished, control
 199         returns to <classname>Zend_Controller_Front</classname>. If the controller has
 200         indicated that another controller should be dispatched by resetting the
 201         dispatched status of the request, the loop continues and another
 202         dispatch is performed. Otherwise, the process ends.
 203     </para>
 204 </sect1>
 205
 206 <!--
 207 vim:se ts=4 sw=4 et:
 208 -->