<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.application.core-functionality.application">
    <title>Zend_Application</title>

    <para>
        <classname>Zend_Application</classname> provides the base functionality of the
        component, and the entry point to your Zend Framework application. It's
        purpose is two-fold: to setup the <acronym>PHP</acronym> environment (including
        autoloading), and to execute your application bootstrap.
    </para>

    <para>
        Typically, you will pass all configuration to the
        <classname>Zend_Application</classname> constructor, but you can also configure
        the object entirely using its own methods. This reference is intended to
        illustrate both use cases.
    </para>

    <table id="zend.application.core-functionality.application.api.options">
        <title>Zend_Application options</title>

        <tgroup cols="2">
            <thead>
                <row>
                    <entry>Option</entry>
                    <entry>Description</entry>
                </row>
            </thead>

            <tbody>
                <row>
                    <entry><emphasis><property>phpSettings</property></emphasis></entry>

                    <entry>
                        <para>
                            Array of <filename>php.ini</filename> settings to use. Keys should be
                            the <filename>php.ini</filename> keys.
                        </para>
                    </entry>
                </row>

                <row>
                    <entry><emphasis><property>includePaths</property></emphasis></entry>

                    <entry>
                        <para>
                            Additional paths to prepend to the <emphasis>include_path</emphasis>.
                            Should be an array of paths.
                        </para>
                    </entry>
                </row>

                <row>
                    <entry><emphasis><property>autoloaderNamespaces</property></emphasis></entry>

                    <entry>
                        <para>
                            Array of additional namespaces to register with the
                            <classname>Zend_Loader_Autoloader</classname> instance.
                        </para>
                    </entry>
                </row>

                <row>
                    <entry><emphasis><property>bootstrap</property></emphasis></entry>

                    <entry>
                        <para>
                            Either the string path to the bootstrap class, or an array
                            with elements for the 'path' and 'class' for the application
                            bootstrap.
                        </para>
                    </entry>
                </row>
            </tbody>
        </tgroup>
    </table>

    <note>
        <title>Option names</title>

        <para>
            Please note that option names are case insensitive.
        </para>
    </note>

    <table id="zend.application.core-functionality.application.api.table">
        <title>Zend_Application Methods</title>

        <tgroup cols="4">
            <thead>
                <row>
                    <entry>Method</entry>
                    <entry>Return Value</entry>
                    <entry>Parameters</entry>
                    <entry>Description</entry>
                </row>
            </thead>

            <tbody>
                <row>
                    <entry>
                        <methodname>__construct($environment, $options = null)</methodname>
                    </entry>

                    <entry><type>Void</type></entry>

                    <entry>
                        <itemizedlist>
                            <listitem>
                                <para>
                                    <varname>$environment</varname>: <emphasis>required</emphasis>,.
                                    String representing the current application
                                    environment. Typical strings might include
                                    "development", "testing", "qa", or
                                    "production", but will be defined by your
                                    organizational requirements.
                                </para>
                            </listitem>

                            <listitem>
                                <para>
                                    <varname>$options</varname>: <emphasis>optional</emphasis>.
                                    Argument may be one of the following values:
                                </para>

                                <itemizedlist>
                                    <listitem>
                                        <para>
                                            <emphasis><type>String</type></emphasis>: path to
                                            a <classname>Zend_Config</classname> file to load
                                            as configuration for your application.
                                            <varname>$environment</varname> will be used
                                            to determine what section of the
                                            configuration to pull.
                                        </para>

                                        <para>
                                            As of 1.10, you may also pass multiple paths containing
                                            config files to be merged into a single configuration.
                                            This assists in reducing config duplication across many
                                            contexts which share common settings (e.g. configs for
                                            <acronym>HTTP</acronym>, or <acronym>CLI</acronym>, each
                                            sharing some characteristics but with their own
                                            conflicting values for others) or merely splitting a
                                            long configuration across many smaller categorised
                                            files. The parameter in this case is an array with a
                                            single key "config" whose value is an array of the
                                            files to merge. Note: this means you either pass a
                                            literal path, or
                                            <command>array("config"=>array("/path1","/path2"[,...]));</command>.
                                        </para>
                                    </listitem>

                                    <listitem>
                                        <para>
                                            <emphasis><type>Array</type></emphasis>: associative
                                            array of configuration data for your application.
                                        </para>
                                    </listitem>

                                    <listitem>
                                        <para>
                                            <emphasis><classname>Zend_Config</classname></emphasis>:
                                            configuration object instance.
                                        </para>
                                    </listitem>
                                </itemizedlist>
                            </listitem>
                        </itemizedlist>
                    </entry>

                    <entry>
                        <para>
                            Constructor. Arguments are as described, and will be
                            used to set initial object state. An instance of
                            <classname>Zend_Loader_Autoloader</classname> is registered
                            during instantiation. Options passed to the
                            constructor are passed to <methodname>setOptions()</methodname>.
                        </para>
                    </entry>
                </row>

                <row>
                    <entry><methodname>getEnvironment()</methodname></entry>
                    <entry><type>String</type></entry>
                    <entry>N/A</entry>

                    <entry>
                        <para>Retrieve the environment string passed to the constructor.</para>
                    </entry>
                </row>

                <row>
                    <entry><methodname>getAutoloader()</methodname></entry>
                    <entry><classname>Zend_Loader_Autoloader</classname></entry>
                    <entry>N/A</entry>

                    <entry>
                        <para>
                            Retrieve the <classname>Zend_Loader_Autoloader</classname>
                            instance registered during instantiation.
                        </para>
                    </entry>
                </row>

                <row>
                    <entry><methodname>setOptions(array $options)</methodname></entry>
                    <entry><classname>Zend_Application</classname></entry>

                    <entry>
                        <itemizedlist>
                            <listitem>
                                <para>
                                    <varname>$options</varname>: <emphasis>required</emphasis>.
                                    An array of application options.
                                </para>
                            </listitem>
                        </itemizedlist>
                    </entry>

                    <entry>
                        <para>
                            All options are stored internally, and calling the
                            method multiple times will merge options. Options
                            matching the various setter methods will be passed
                            to those methods. As an example, the option
                            "phpSettings" will then be passed to
                            <methodname>setPhpSettings()</methodname>. (Option names are
                            case insensitive.)
                        </para>
                    </entry>
                </row>

                <row>
                    <entry><methodname>getOptions()</methodname></entry>
                    <entry><type>Array</type></entry>
                    <entry>N/A</entry>

                    <entry>
                        <para>
                            Retrieve all options used to initialize the object;
                            could be used to cache <classname>Zend_Config</classname>
                            options to a serialized format between requests.
                        </para>
                    </entry>
                </row>

                <row>
                    <entry><methodname>hasOption($key)</methodname></entry>
                    <entry><type>Boolean</type></entry>
                    <entry>
                        <itemizedlist>
                            <listitem>
                                <para>
                                    <varname>$key</varname>: String option key to lookup
                                </para>
                            </listitem>
                        </itemizedlist>
                    </entry>

                    <entry>
                        <para>
                            Determine whether or not an option with the
                            specified key has been registered. Keys are case insensitive.
                        </para>
                    </entry>
                </row>

                <row>
                    <entry><methodname>getOption($key)</methodname></entry>
                    <entry><type>Mixed</type></entry>
                    <entry>
                        <itemizedlist>
                            <listitem>
                                <para><varname>$key</varname>: String option key to lookup</para>
                            </listitem>
                        </itemizedlist>
                    </entry>

                    <entry>
                        <para>
                            Retrieve the option value of a given key. Returns
                            <constant>NULL</constant> if the key does not exist.
                        </para>
                    </entry>
                </row>

                <row>
                    <entry>
                        <methodname>setPhpSettings(array $settings, $prefix = '')</methodname>
                    </entry>

                    <entry><classname>Zend_Application</classname></entry>

                    <entry>
                        <itemizedlist>
                            <listitem>
                                <para>
                                    <varname>$settings</varname>: <emphasis>required</emphasis>.
                                    Associative array of <acronym>PHP</acronym>
                                    <acronym>INI</acronym> settings.
                                </para>
                            </listitem>

                            <listitem>
                                <para>
                                    <varname>$prefix</varname>: <emphasis>optional</emphasis>.
                                    String prefix with which to prepend option keys. Used
                                    internally to allow mapping nested arrays to dot-separated
                                    <filename>php.ini</filename> keys. In normal usage, this
                                    argument should never be passed by a user.
                                </para>
                            </listitem>
                        </itemizedlist>
                    </entry>

                    <entry>
                        <para>
                            Set run-time <filename>php.ini</filename> settings. Dot-separated
                            settings may be nested hierarchically (which may occur
                            with <acronym>INI</acronym> <classname>Zend_Config</classname> files)
                            via an array-of-arrays, and will still resolve correctly.
                        </para>
                    </entry>
                </row>

                <row>
                    <entry>
                        <methodname>setAutoloaderNamespaces(array $namespaces)</methodname>
                    </entry>

                    <entry><classname>Zend_Application</classname></entry>

                    <entry>
                        <itemizedlist>
                            <listitem>
                                <para>
                                    <varname>$namespaces</varname>: <emphasis>required</emphasis>.
                                    Array of strings representing the namespaces to
                                    register with the <classname>Zend_Loader_Autoloader</classname>
                                    instance.
                                </para>
                            </listitem>
                        </itemizedlist>
                    </entry>

                    <entry>
                        <para>
                            Register namespaces with the
                            <classname>Zend_Loader_Autoloader</classname> instance.
                        </para>
                    </entry>
                </row>

                <row>
                    <entry><methodname>setBootstrap($path, $class = null)</methodname></entry>
                    <entry><classname>Zend_Application</classname></entry>

                    <entry>
                        <itemizedlist>
                            <listitem>
                                <para>
                                    <varname>$path</varname>: <emphasis>required</emphasis>. May be
                                    either a
                                    <classname>Zend_Application_Bootstrap_Bootstrapper</classname>
                                    instance, a string path to the bootstrap class, an
                                    associative array of classname =&gt; filename, or an associative
                                    array with the keys 'class' and 'path'.
                                </para>
                            </listitem>

                            <listitem>
                                <para>
                                    <varname>$class</varname>: <emphasis>optional</emphasis>.
                                    If <varname>$path</varname> is a string,
                                    <varname>$class</varname> may be specified, and should
                                    be a string class name of the class contained in
                                    the file represented by path.
                                </para>
                            </listitem>
                        </itemizedlist>
                    </entry>
                </row>

                <row>
                    <entry><methodname>getBootstrap()</methodname></entry>

                    <entry>
                        <constant>NULL</constant> |
                        <classname>Zend_Application_Bootstrap_Bootstrapper</classname>
                    </entry>

                    <entry>N/A</entry>
                    <entry><para>Retrieve the registered bootstrap instance.</para></entry>
                </row>

                <row>
                    <entry><methodname>bootstrap()</methodname></entry>
                    <entry><type>Void</type></entry>
                    <entry>N/A</entry>
                    <entry>
                        <para>
                            Call the bootstrap's <methodname>bootstrap()</methodname>
                            method to bootstrap the application.
                        </para>
                    </entry>
                </row>

                <row>
                    <entry><methodname>run()</methodname></entry>
                    <entry><type>Void</type></entry>
                    <entry>N/A</entry>
                    <entry>
                        <para>
                            Call the bootstrap's <methodname>run()</methodname>
                            method to dispatch the application.
                        </para>
                    </entry>
                </row>
            </tbody>
        </tgroup>
    </table>
</sect2>
