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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.controller.modular">
   4     <title>Using a Conventional Modular Directory Structure</title>
   5
   6     <sect2 id="zend.controller.modular.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             The Conventional Modular directory structure allows you to separate
  11             different <acronym>MVC</acronym> applications into self-contained units, and re-use
  12             them with different front controllers. To illustrate such a
  13             directory structure:
  14         </para>
  15
  16         <programlisting language="txt"><![CDATA[
  17 docroot/
  18     index.php
  19 application/
  20     default/
  21         controllers/
  22             IndexController.php
  23             FooController.php
  24         models/
  25         views/
  26             scripts/
  27                 index/
  28                 foo/
  29             helpers/
  30             filters/
  31     blog/
  32         controllers/
  33             IndexController.php
  34         models/
  35         views/
  36             scripts/
  37                 index/
  38             helpers/
  39             filters/
  40     news/
  41         controllers/
  42             IndexController.php
  43             ListController.php
  44         models/
  45         views/
  46             scripts/
  47                 index/
  48                 list/
  49             helpers/
  50             filters/
  51 ]]></programlisting>
  52
  53         <para>
  54             In this paradigm, the module name serves as a prefix to the
  55             controllers it contains. The above example contains three
  56             module controllers, '<classname>Blog_IndexController</classname>',
  57             '<classname>News_IndexController</classname>', and
  58             '<classname>News_ListController</classname>'.
  59             Two global controllers, '<classname>IndexController</classname>' and
  60             '<classname>FooController</classname>' are also defined; neither of these will be
  61             namespaced. This directory structure will be used for examples in
  62             this chapter.
  63         </para>
  64
  65         <note>
  66             <title>No Namespacing in the Default Module</title>
  67
  68             <para>
  69                 Note that in the default module, controllers do not need a
  70                 namespace prefix. Thus, in the example above, the controllers in
  71                 the default module do not need a prefix of 'Default_' -- they
  72                 are simply dispatched according to their base controller name:
  73                 '<classname>IndexController</classname>' and
  74                 '<classname>FooController</classname>'. A namespace prefix is
  75                 used in all other modules, however.
  76             </para>
  77         </note>
  78
  79         <para>
  80             So, how do you implement such a directory layout using the Zend
  81             Framework <acronym>MVC</acronym> components?
  82         </para>
  83     </sect2>
  84
  85     <sect2 id="zend.controller.modular.directories">
  86         <title>Specifying Module Controller Directories</title>
  87
  88         <para>
  89             The first step to making use of modules is to modify how you specify
  90             the controller directory list in the front controller. In the basic
  91             <acronym>MVC</acronym> series, you pass either an array or a string to
  92             <methodname>setControllerDirectory()</methodname>, or a path to
  93             <methodname>addControllerDirectory()</methodname>. When using modules, you need
  94             to alter your calls to these methods slightly.
  95         </para>
  96
  97         <para>
  98             With <methodname>setControllerDirectory()</methodname>, you will need to pass an
  99             associative array and specify key and value pairs of module
 100             name and directory paths. The special key <property>default</property> will be
 101             used for global controllers (those not needing a module namespace).
 102             All entries should contain a string key pointing to a single path,
 103             and the <property>default</property> key must be present. As an example:
 104         </para>
 105
 106         <programlisting language="php"><![CDATA[
 107 $front->setControllerDirectory(array(
 108     'default' => '/path/to/application/controllers',
 109     'blog'    => '/path/to/application/blog/controllers'
 110 ));
 111 ]]></programlisting>
 112
 113         <para>
 114             <methodname>addControllerDirectory()</methodname> will take an optional second
 115             argument. When using modules, pass the module name as the second
 116             argument; if not specified, the path will be added to the
 117             <emphasis>default</emphasis> namespace. As an example:
 118         </para>
 119
 120         <programlisting language="php"><![CDATA[
 121 $front->addControllerDirectory('/path/to/application/news/controllers',
 122                                'news');
 123 ]]></programlisting>
 124
 125         <para>
 126             Saving the best for last, the easiest way to specify module
 127             directories is to do so en masse, with all modules under a common
 128             directory and sharing the same structure. This can be done with
 129             <methodname>addModuleDirectory()</methodname>:
 130         </para>
 131
 132         <programlisting language="php"><![CDATA[
 133 /**
 134  * Assuming the following directory structure:
 135  * application/
 136  *     modules/
 137  *         default/
 138  *             controllers/
 139  *         foo/
 140  *             controllers/
 141  *         bar/
 142  *             controllers/
 143  */
 144 $front->addModuleDirectory('/path/to/application/modules');
 145 ]]></programlisting>
 146
 147         <para>
 148             The above example will define the <emphasis>default</emphasis>,
 149             <emphasis>foo</emphasis>, and <emphasis>bar</emphasis> modules, each pointing to the
 150             <filename>controllers/</filename> subdirectory of their respective module.
 151         </para>
 152
 153         <para>
 154             You may customize the controller subdirectory to use within your
 155             modules by using <methodname>setModuleControllerDirectoryName()</methodname>:
 156         </para>
 157
 158         <programlisting language="php"><![CDATA[
 159 /**
 160  * Change the controllers subdirectory to be 'con'
 161  * application/
 162  *     modules/
 163  *         default/
 164  *             con/
 165  *         foo/
 166  *             con/
 167  *         bar/
 168  *             con/
 169  */
 170 $front->setModuleControllerDirectoryName('con');
 171 $front->addModuleDirectory('/path/to/application/modules');
 172 ]]></programlisting>
 173
 174         <note>
 175             <para>
 176                 You can indicate that no controller subdirectory be used for your
 177                 modules by passing an empty value to
 178                 <methodname>setModuleControllerDirectoryName()</methodname>.
 179             </para>
 180         </note>
 181     </sect2>
 182
 183     <sect2 id="zend.controller.modular.router">
 184         <title>Routing to Modules</title>
 185
 186         <para>
 187             The default route in <classname>Zend_Controller_Router_Rewrite</classname> is
 188             an object of type <classname>Zend_Controller_Router_Route_Module</classname>.
 189             This route expects one of the following routing schemas:
 190         </para>
 191
 192         <itemizedlist>
 193             <listitem><para><filename>:module/:controller/:action/*</filename></para></listitem>
 194             <listitem><para><filename>:controller/:action/*</filename></para></listitem>
 195         </itemizedlist>
 196
 197         <para>
 198             In other words, it will match a controller and action by themselves
 199             or with a preceding module. The rules for matching specify that a
 200             module will only be matched if a key of the same name exists in the
 201             controller directory array passed to the front controller and
 202             dispatcher.
 203         </para>
 204     </sect2>
 205
 206     <sect2 id="zend.controller.modular.defaultcontroller">
 207         <title>Module or Global Default Controller</title>
 208
 209         <para>
 210             In the default router, if a controller was not specified in the <acronym>URL</acronym>,
 211             a default controller is used (<classname>IndexController</classname>, unless
 212             otherwise requested). With modular controllers, if a module has been
 213             specified but no controller, the dispatcher first looks for this
 214             default controller in the module path, and then falls back on the
 215             default controller found in the 'default', global, namespace.
 216         </para>
 217
 218         <para>
 219             If you wish to always default to the global namespace, set the
 220             <varname>$useDefaultControllerAlways</varname> parameter in the front controller:
 221         </para>
 222
 223         <programlisting language="php"><![CDATA[
 224 $front->setParam('useDefaultControllerAlways', true);
 225 ]]></programlisting>
 226     </sect2>
 227 </sect1>
 228 <!--
 229 vim:se ts=4 sw=4 et:
 230 -->