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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.controller.modular">
    <title>Using a Conventional Modular Directory Structure</title>

    <sect2 id="zend.controller.modular.introduction">
        <title>Introduction</title>

        <para>
            The Conventional Modular directory structure allows you to separate
            different <acronym>MVC</acronym> applications into self-contained units, and re-use
            them with different front controllers. To illustrate such a
            directory structure:
        </para>

        <programlisting language="txt"><![CDATA[
docroot/
    index.php
application/
    default/
        controllers/
            IndexController.php
            FooController.php
        models/
        views/
            scripts/
                index/
                foo/
            helpers/
            filters/
    blog/
        controllers/
            IndexController.php
        models/
        views/
            scripts/
                index/
            helpers/
            filters/
    news/
        controllers/
            IndexController.php
            ListController.php
        models/
        views/
            scripts/
                index/
                list/
            helpers/
            filters/
]]></programlisting>

        <para>
            In this paradigm, the module name serves as a prefix to the
            controllers it contains. The above example contains three
            module controllers, '<classname>Blog_IndexController</classname>',
            '<classname>News_IndexController</classname>', and
            '<classname>News_ListController</classname>'.
            Two global controllers, '<classname>IndexController</classname>' and
            '<classname>FooController</classname>' are also defined; neither of these will be
            namespaced. This directory structure will be used for examples in
            this chapter.
        </para>

        <note>
            <title>No Namespacing in the Default Module</title>

            <para>
                Note that in the default module, controllers do not need a
                namespace prefix. Thus, in the example above, the controllers in
                the default module do not need a prefix of 'Default_' -- they
                are simply dispatched according to their base controller name:
                '<classname>IndexController</classname>' and
                '<classname>FooController</classname>'. A namespace prefix is
                used in all other modules, however.
            </para>
        </note>

        <para>
            So, how do you implement such a directory layout using the Zend
            Framework <acronym>MVC</acronym> components?
        </para>
    </sect2>

    <sect2 id="zend.controller.modular.directories">
        <title>Specifying Module Controller Directories</title>

        <para>
            The first step to making use of modules is to modify how you specify
            the controller directory list in the front controller. In the basic
            <acronym>MVC</acronym> series, you pass either an array or a string to
            <methodname>setControllerDirectory()</methodname>, or a path to
            <methodname>addControllerDirectory()</methodname>. When using modules, you need
            to alter your calls to these methods slightly.
        </para>

        <para>
            With <methodname>setControllerDirectory()</methodname>, you will need to pass an
            associative array and specify key and value pairs of module
            name and directory paths. The special key <property>default</property> will be
            used for global controllers (those not needing a module namespace).
            All entries should contain a string key pointing to a single path,
            and the <property>default</property> key must be present. As an example:
        </para>

        <programlisting language="php"><![CDATA[
$front->setControllerDirectory(array(
    'default' => '/path/to/application/controllers',
    'blog'    => '/path/to/application/blog/controllers'
));
]]></programlisting>

        <para>
            <methodname>addControllerDirectory()</methodname> will take an optional second
            argument. When using modules, pass the module name as the second
            argument; if not specified, the path will be added to the
            <emphasis>default</emphasis> namespace. As an example:
        </para>

        <programlisting language="php"><![CDATA[
$front->addControllerDirectory('/path/to/application/news/controllers',
                               'news');
]]></programlisting>

        <para>
            Saving the best for last, the easiest way to specify module
            directories is to do so en masse, with all modules under a common
            directory and sharing the same structure. This can be done with
            <methodname>addModuleDirectory()</methodname>:
        </para>

        <programlisting language="php"><![CDATA[
/**
 * Assuming the following directory structure:
 * application/
 *     modules/
 *         default/
 *             controllers/
 *         foo/
 *             controllers/
 *         bar/
 *             controllers/
 */
$front->addModuleDirectory('/path/to/application/modules');
]]></programlisting>

        <para>
            The above example will define the <emphasis>default</emphasis>,
            <emphasis>foo</emphasis>, and <emphasis>bar</emphasis> modules, each pointing to the
            <filename>controllers/</filename> subdirectory of their respective module.
        </para>

        <para>
            You may customize the controller subdirectory to use within your
            modules by using <methodname>setModuleControllerDirectoryName()</methodname>:
        </para>

        <programlisting language="php"><![CDATA[
/**
 * Change the controllers subdirectory to be 'con'
 * application/
 *     modules/
 *         default/
 *             con/
 *         foo/
 *             con/
 *         bar/
 *             con/
 */
$front->setModuleControllerDirectoryName('con');
$front->addModuleDirectory('/path/to/application/modules');
]]></programlisting>

        <note>
            <para>
                You can indicate that no controller subdirectory be used for your
                modules by passing an empty value to
                <methodname>setModuleControllerDirectoryName()</methodname>.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.controller.modular.router">
        <title>Routing to Modules</title>

        <para>
            The default route in <classname>Zend_Controller_Router_Rewrite</classname> is
            an object of type <classname>Zend_Controller_Router_Route_Module</classname>.
            This route expects one of the following routing schemas:
        </para>

        <itemizedlist>
            <listitem><para><filename>:module/:controller/:action/*</filename></para></listitem>
            <listitem><para><filename>:controller/:action/*</filename></para></listitem>
        </itemizedlist>

        <para>
            In other words, it will match a controller and action by themselves
            or with a preceding module. The rules for matching specify that a
            module will only be matched if a key of the same name exists in the
            controller directory array passed to the front controller and
            dispatcher.
        </para>
    </sect2>

    <sect2 id="zend.controller.modular.defaultcontroller">
        <title>Module or Global Default Controller</title>

        <para>
            In the default router, if a controller was not specified in the <acronym>URL</acronym>,
            a default controller is used (<classname>IndexController</classname>, unless
            otherwise requested). With modular controllers, if a module has been
            specified but no controller, the dispatcher first looks for this
            default controller in the module path, and then falls back on the
            default controller found in the 'default', global, namespace.
        </para>

        <para>
            If you wish to always default to the global namespace, set the
            <varname>$useDefaultControllerAlways</varname> parameter in the front controller:
        </para>

        <programlisting language="php"><![CDATA[
$front->setParam('useDefaultControllerAlways', true);
]]></programlisting>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->