repo_zf1/documentation/manual/en/ref/project-structure.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<appendix id="project-structure">
    <title>Recommended Project Structure for Zend Framework MVC Applications</title>

    <sect1 id="project-structure.overview">
        <title>Overview</title>

        <para>
            Many developers seek guidance on the best project structure for a Zend Framework project
            in a relatively flexible environment. A "flexible" environment is one in which the 
            developer can manipulate their file systems and web server configurations as needed to 
            achieve the most ideal project structure to run and secure their application. The 
            default project structure will assume that the developer has such flexibility at their 
            disposal.
        </para>

        <para>
            The following directory structure is designed to be maximally extensible for complex 
            projects, while providing a simple subset of folder and files for project with simpler 
            requirements. This structure also works without alteration for both modular and 
            non-modular ZF applications. The <filename>.htaccess</filename> files require URL 
            rewrite functionality in the web server as described in the <link 
                linkend="project-structure.rewrite-guide">Rewrite Configuration Guide</link>, also 
            included in this appendix.
        </para>

        <para>
            It is not the intention that this project structure will support all possible ZF project
            requirements. The default project profile used by <classname>Zend_Tool</classname> 
            reflect this project structure, but applications with requirements not supported by this
            structure should use a custom project profile.
        </para>
    </sect1>

    <sect1 id="project-structure.project">
        <title>Recommended Project Directory Structure</title>

        <literallayout>
&lt;project name&gt;/
    application/
        configs/
            application.ini
        controllers/
            helpers/
        layouts/
            filters/
            helpers/
            scripts/
        models/
        modules/
        services/
        views/
            filters/
            helpers/
            scripts/
        Bootstrap.php
    data/
        cache/
        indexes/
        locales/
        logs/
        sessions/
        uploads/
    docs/
    library/
    public/
        css/
        images/
        js/
        .htaccess
        index.php
    scripts/
        jobs/
        build/
    temp/
    tests/
        </literallayout>

        <para>
            The following describes the use cases for each directory as listed.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>application/</emphasis>: This directory contains your application. It
                    will house the MVC system, as well as configurations, services used, and your 
                    bootstrap file.
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <emphasis>configs/</emphasis>: The application-wide configuration 
                            directory.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <emphasis>controllers/</emphasis>, <emphasis>models/</emphasis>, and 
                            <emphasis>views/</emphasis>: These directories serve as the default 
                            controller/model/view directories. Having these three directories inside
                            the application directory provides the best layout for starting a simple 
                            project as well as starting a modular project that has global 
                            controllers/models/views.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <emphasis>controllers/helpers/</emphasis>: These directories will 
                            contain action helpers. Action helpers will be namespaced either as 
                            "Controller_Helper_" for the default module or 
                            "&lt;Module&gt;_Controller_Helper" in other modules.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <emphasis>layouts/</emphasis>: This layout directory is for MCV-based
                            layouts. Since <classname>Zend_Layout</classname> is capable of MVC- 
                            and non-MVC-based layouts, the location of this directory reflects that 
                            layouts are not on a 1-to-1 relationship with controllers and are 
                            independent of templates within <filename>views/</filename>.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <emphasis>modules/</emphasis>: Modules allow a developer to group a set 
                            of related controllers into a logically organized group. The structure 
                            under the modules directory would resemble the structure under the 
                            application directory.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <emphasis>services</emphasis>: This directory is for your application 
                            specific web-service files that are provided by your application, or for
                            implementing a <ulink 
                            url="http://www.martinfowler.com/eaaCatalog/serviceLayer.html">Service 
                            Layer</ulink> for your models.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <emphasis>Bootstrap.php</emphasis>: This file is the entry point for 
                            your application, and should implement 
                            <interfacename>Zend_Application_Bootstrap_Bootstrapper</interfacename>. 
                            The purpose for this file is to bootstrap the application and make 
                            components available to the application by initializing them.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <emphasis>data</emphasis>: This directory provides a place to store application 
                    data that is volatile and possibly temporary. The disturbance of data in this 
                    directory might cause the application to fail. Also, the information in this 
                    directory may or may not be committed to a subversion repository. Examples of 
                    things in this directory are session files, cache files, sqlite databases, logs 
                    and indexes.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>docs/</emphasis>: This directory contains documentation, either 
                    generated or directly authored.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>library/</emphasis>: This directory is for common libraries on which 
                    the application depends, and should be on the PHP 
                    <varname>include_path</varname>.  Developers should place their application's 
                    library code under this directory in a unique namespace, following the 
                    guidelines established in the PHP manual's <ulink 
                        url="http://www.php.net/manual/en/userlandnaming.php">Userland Naming 
                    Guide</ulink>, as well as those established by Zend itself.  This may directory 
                    may also include Zend Framework itself; if so, you would house it in 
                    <filename>library/Zend/</filename>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>public/</emphasis>: This directory contains all public files for your 
                    application.  <filename>index.php</filename> sets up and invokes 
                    <classname>Zend_Application</classname>, which in turn invokes the 
                    <filename>application/Bootstrap.php</filename> file, resulting in dispatching 
                    the front controller. The web root of your web server would typically be set to 
                    this directory.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>scripts/</emphasis>: This directory contains maintenance and/or build 
                    scripts. Such scripts might include command line, cron, or phing build scripts 
                    that are not executed at runtime but are part of the correct functioning of the 
                    application.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>temp/</emphasis>: The <filename>temp/</filename> folder is set aside 
                    for transient application data. This information would not typically be 
                    committed to the applications svn repository. If data under the 
                    <filename>temp/</filename> directory were deleted, the application should be 
                    able to continue running with a possible decrease in performance until data is 
                    once again restored/recached.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>tests/</emphasis>: This directory contains application tests. These 
                    could be hand-written, PHPUnit tests, Selenium-RC based tests or based on some 
                    other testing framework. By default, library code can be tested by mimicing the 
                    directory structure of your <filename>library/</filename> directory. 
                    Additionally, functional tests for your application could be written mimicing 
                    the <filename>application/</filename> directory structure (including the 
                    application subdirectory).
                </para>
            </listitem>
        </itemizedlist>
    </sect1>

    <sect1 id="project-structure.filesystem">
        <title>Module Structure</title>

        <para>
            The directory structure for modules should mimic that of the 
            <filename>application/</filename> directory in the recommended project structure:
        </para>

        <literallayout>
&lt;modulename&gt;/
    configs/
        application.ini
    controllers/
        helpers/
    layouts/
        filters/
        helpers/
        scripts/
    models/
    services/
    views/
        filters/
        helpers/
        scripts/
    Bootstrap.php
        </literallayout>

        <para>
            The purpose of these directories remains exactly the same as for the recommended 
            project directory structure.
        </para>
    </sect1>

    <sect1 id="project-structure.rewrite">
        <title>Rewrite Configuration Guide</title>

        <para>
            URL rewriting is a common function of HTTP servers. However, the rules and configuration 
            differ widely between them. Below are some common approaches across a variety of popular 
            web servers available at the time of writing.
        </para>

        <sect2 id="project-structure.rewrite.apache">
            <title>Apache HTTP Server</title>

            <para>
                All examples that follow use <application>mod_rewrite</application>, an official 
                module that comes bundled with Apache. To use it, 
                <application>mod_rewrite</application> must either be included at compile time or 
                enabled as a Dynamic Shared Object (DSO). Please consult the <ulink 
                    url="http://httpd.apache.org/docs/">Apache documentation</ulink> for your 
                version for more information.
            </para>

            <sect3 id="project-structure.rewrite.apache.vhost">
                <title>Rewriting inside a VirtualHost</title>

                <para>
                    Here is a very basic virtual host definition. These rules direct all requests 
                    to <filename>index.php</filename>, except when a matching file is found under 
                    the <option>document_root</option>.
                </para>

                <programlisting language="xml"><![CDATA[
<VirtualHost my.domain.com:80>
    ServerName   my.domain.com
    DocumentRoot /path/to/server/root/my.domain.com/public

    RewriteEngine off

    <Location />
        RewriteEngine On
        RewriteCond %{REQUEST_FILENAME} -s [OR]
        RewriteCond %{REQUEST_FILENAME} -l [OR]
        RewriteCond %{REQUEST_FILENAME} -d
        RewriteRule ^.*$ - [NC,L]
        RewriteRule ^.*$ /index.php [NC,L]
    </Location>
</VirtualHost>
]]></programlisting>

                <para>
                    Note the slash ("/") prefixing <filename>index.php</filename>; the rules for 
                    <filename>.htaccess</filename> differ in this regard.
                </para>
            </sect3>

            <sect3 id="project-structure.rewrite.apache.htaccess">
                <title>Rewriting within a .htaccess file</title>

                <para>
                    Below is a sample <filename>.htaccess</filename> file that utilizes 
                    <application>mod_rewrite</application>. It is similar to the virtual host 
                    configuration, except that it specifies only the rewrite rules, and the leading 
                    slash is omitted from <filename>index.php</filename>.
                </para>

                <programlisting language="text"><![CDATA[
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} -s [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.*$ - [NC,L]
RewriteRule ^.*$ index.php [NC,L]
]]></programlisting>
            </sect3>

            <para>
                There are many ways to configure <application>mod_rewrite</application>; if you 
                would like more information, see Jayson Minard's <ulink 
                    url="http://devzone.zend.com/a/70">Blueprint for PHP Applications: 
                Bootstrapping</ulink>.
            </para>
        </sect2>

        <sect2 id="project-structure.rewrite.iis">
            <title>Microsoft Internet Information Server</title>

            <para>
                As of version 7.0, IIS now ships with a standard rewrite engine.  You may use the 
                following configuration to create the appropriate rewrite rules.
            </para>

            <programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <rule name="Imported Rule 1" stopProcessing="true">
                    <match url="^.*$" />
                    <conditions logicalGrouping="MatchAny">
                        <add input="{REQUEST_FILENAME}"
                             matchType="IsFile" pattern=""
                             ignoreCase="false" />
                        <add input="{REQUEST_FILENAME}"
                             matchType="IsDirectory"
                             pattern=""
                             ignoreCase="false" />
                    </conditions>
                    <action type="None" />
                </rule>
                <rule name="Imported Rule 2" stopProcessing="true">
                    <match url="^.*$" />
                    <action type="Rewrite" url="index.php" />
                </rule>
            </rules>
        </rewrite>
    </system.webServer>
</configuration>
]]></programlisting>
        </sect2>
    </sect1>
</appendix>