repo_zf1/documentation/manual/en/module_specs/Zend_Application-AvailableResources-Frontcontroller.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.application.available-resources.frontcontroller">
    <title>Zend_Application_Resource_Frontcontroller</title>

    <para>
        Probably the most common resource you will load with
        <classname>Zend_Application</classname> will be the Front Controller resource,
        which provides the ability to configure
        <classname>Zend_Controller_Front</classname>. This resource provides the ability
        to set arbitrary front controller parameters, specify plugins to
        initialize, and much more.
    </para>

    <para>
        Once initialized, the resource assigns the <varname>$frontController</varname>
        property of the bootstrap to the <classname>Zend_Controller_Front</classname>
        instance.
    </para>

    <para>
        Available configuration keys include the following, and are case
        insensitive:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <emphasis><property>controllerDirectory</property></emphasis>: either a string value
                specifying a single controller directory, or an array of
                module to controller directory pairs.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis><property>moduleControllerDirectoryName</property></emphasis>: a string
                value indicating the subdirectory under a module that contains controllers.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis><property>moduleDirectory</property></emphasis>: directory under which
                modules may be found.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis><property>defaultControllerName</property></emphasis>: base name of the
                default controller (normally "index").
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis><property>defaultAction</property></emphasis>: base name of the default
                action (normally "index").
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis><property>defaultModule</property></emphasis>: base name of the default
                module (normally "default").
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis><property>baseUrl</property></emphasis>: explicit base
                <acronym>URL</acronym> to the application (normally auto-detected).
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis><property>plugins</property></emphasis>: array of front controller plugin
                class names. The resource will instantiate each class (with no constructor
                arguments) and then register the instance with the front controller. If you want to
                register a plugin with a particular stack index, you need to provide an array with
                two keys <property>class</property> and <property>stackIndex</property>.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis><property>params</property></emphasis>: array of key to value pairs to
                register with the front controller.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis><property>returnresponse</property></emphasis>: whether or not to return
                the response object after dispatching the front controller. Value should be a
                boolean; by default, this is disabled.
            </para>
        </listitem>
        
        <listitem>
            <para>
                <emphasis><property>dispatcher</property></emphasis>: allows overriding the default 
                dispatcher.  Has two subkeys, <property>class</property> (the classname of new dispatcher)
                and <property>params</property>, an array of parameters to pass to the dispatcher constructor.
            </para>
            
            <example id="zend.application.available-resources.frontcontroller.configExample">
                <title>Overriding the dispatcher</title>

                <programlisting language="ini"><![CDATA[
        [production]
        resources.frontController.dispatcher.class = "My_Custom_Dispatcher"
        resources.frontController.dispatcher.params.foo = "bar"
        resources.frontController.dispatcher.params.baz = "grok"
        ]]></programlisting>
            </example>
            
        </listitem>
        
    </itemizedlist>

    <para>
        If an unrecognized key is provided, it is registered as a front
        controller parameter by passing it to <methodname>setParam()</methodname>.
    </para>

    <example id="zend.application.available-resources.frontcontroller.configExample">
        <title>Sample Front Controller resource configuration</title>

        <para>
            Below is a sample <acronym>INI</acronym> snippet showing how to configure the front
            controller resource.
        </para>

        <programlisting language="ini"><![CDATA[
[production]
resources.frontController.controllerDirectory = APPLICATION_PATH "/controllers"
resources.frontController.moduleControllerDirectoryName = "actions"
resources.frontController.moduleDirectory = APPLICATION_PATH "/modules"
resources.frontController.defaultControllerName = "site"
resources.frontController.defaultAction = "home"
resources.frontController.defaultModule = "static"
resources.frontController.baseUrl = "/subdir"
resources.frontController.plugins.foo = "My_Plugin_Foo"
resources.frontController.plugins.bar = "My_Plugin_Bar"
resources.frontController.plugins.baz.class = "My_Plugin_Baz"
resources.frontController.plugins.baz.stackIndex = 123
resources.frontController.returnresponse = 1
resources.frontController.env = APPLICATION_ENV

; The following proxies to:
; Zend_Controller_Action_HelperBroker::addPath('Helper_Path', $helperPrefix);
resources.frontController.actionHelperPaths.HELPER_Prefix = "My/Helper/Path"
]]></programlisting>
    </example>

    <example id="zend.application.available-resources.frontcontroller.propertyExample">
        <title>Retrieving the Front Controller in your bootstrap</title>

        <para>
            Once your Front Controller resource has been initialized, you can
            fetch the Front Controller instance via the
            <varname>$frontController</varname> property of your bootstrap.
        </para>

        <programlisting language="php"><![CDATA[
$bootstrap->bootstrap('frontController');
$front = $bootstrap->frontController;
]]></programlisting>
    </example>
</sect2>