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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <appendix id="project-structure">
   4     <title>Recommended Project Structure for Zend Framework MVC Applications</title>
   5
   6     <sect1 id="project-structure.overview">
   7         <title>Overview</title>
   8
   9         <para>
  10             Many developers seek guidance on the best project structure for a Zend Framework project
  11             in a relatively flexible environment. A "flexible" environment is one in which the
  12             developer can manipulate their file systems and web server configurations as needed to
  13             achieve the most ideal project structure to run and secure their application. The
  14             default project structure will assume that the developer has such flexibility at their
  15             disposal.
  16         </para>
  17
  18         <para>
  19             The following directory structure is designed to be maximally extensible for complex
  20             projects, while providing a simple subset of folder and files for project with simpler
  21             requirements. This structure also works without alteration for both modular and
  22             non-modular Zend Framework applications. The <filename>.htaccess</filename> files
  23             require <acronym>URL</acronym> rewrite functionality in the web server as described in
  24             the <link linkend="project-structure.rewrite">Rewrite Configuration Guide</link>, also
  25             included in this appendix.
  26         </para>
  27
  28         <para>
  29             It is not the intention that this project structure will support all possible Zend
  30             Framework project requirements. The default project profile used by
  31             <classname>Zend_Tool</classname> reflect this project structure, but applications with
  32             requirements not supported by this structure should use a custom project profile.
  33         </para>
  34     </sect1>
  35
  36     <sect1 id="project-structure.project">
  37         <title>Recommended Project Directory Structure</title>
  38
  39         <programlisting language="text"><![CDATA[
  40 <project name>/
  41     application/
  42         configs/
  43             application.ini
  44         controllers/
  45             helpers/
  46         forms/
  47         layouts/
  48             filters/
  49             helpers/
  50             scripts/
  51         models/
  52         modules/
  53         services/
  54         views/
  55             filters/
  56             helpers/
  57             scripts/
  58         Bootstrap.php
  59     data/
  60         cache/
  61         indexes/
  62         locales/
  63         logs/
  64         sessions/
  65         uploads/
  66     docs/
  67     library/
  68     public/
  69         css/
  70         images/
  71         js/
  72         .htaccess
  73         index.php
  74     scripts/
  75         jobs/
  76         build/
  77     temp/
  78     tests/
  79 ]]></programlisting>
  80
  81         <para>
  82             The following describes the use cases for each directory as listed.
  83         </para>
  84
  85         <itemizedlist>
  86             <listitem>
  87                 <para>
  88                     <emphasis><filename>application/</filename></emphasis>: This directory contains
  89                     your application. It will house the <acronym>MVC</acronym> system, as well as
  90                     configurations, services used, and your bootstrap file.
  91                 </para>
  92
  93                 <itemizedlist>
  94                     <listitem>
  95                         <para>
  96                             <emphasis><filename>configs/</filename></emphasis>: The
  97                             application-wide configuration directory.
  98                         </para>
  99                     </listitem>
 100
 101                     <listitem>
 102                         <para>
 103                             <emphasis><filename>controllers/</filename></emphasis>,
 104                             <emphasis><filename>models/</filename></emphasis>, and
 105                             <emphasis><filename>views/</filename></emphasis>: These directories
 106                             serve as the default controller, model or view directories. Having
 107                             these three directories inside the application directory provides the
 108                             best layout for starting a simple project as well as starting a modular
 109                             project that has global <filename>controllers/models/views</filename>.
 110                         </para>
 111                     </listitem>
 112
 113                     <listitem>
 114                         <para>
 115                             <emphasis><filename>controllers/helpers/</filename></emphasis>: These
 116                             directories will contain action helpers. Action helpers will be
 117                             namespaced either as "<classname>Controller_Helper_</classname>" for
 118                             the default module or "&lt;Module&gt;_Controller_Helper" in other
 119                             modules.
 120                         </para>
 121                     </listitem>
 122
 123                     <listitem>
 124                         <para>
 125                             <emphasis><filename>layouts/</filename></emphasis>: This layout
 126                             directory is for <acronym>MVC</acronym>-based layouts. Since
 127                             <classname>Zend_Layout</classname> is capable of
 128                             <acronym>MVC</acronym>- and non-<acronym>MVC</acronym>-based layouts,
 129                             the location of this directory reflects that layouts are not on a
 130                             1-to-1 relationship with controllers and are independent of templates
 131                             within <filename>views/</filename>.
 132                         </para>
 133                     </listitem>
 134
 135                     <listitem>
 136                         <para>
 137                             <emphasis><filename>modules/</filename></emphasis>: Modules allow a
 138                             developer to group a set of related controllers into a logically
 139                             organized group. The structure under the modules directory would
 140                             resemble the structure under the application directory.
 141                         </para>
 142                     </listitem>
 143
 144                     <listitem>
 145                         <para>
 146                             <emphasis><filename>services/</filename></emphasis>: This directory is
 147                             for your application specific web-service files that are provided by
 148                             your application, or for implementing a <ulink
 149                                 url="http://www.martinfowler.com/eaaCatalog/serviceLayer.html">Service
 150                                 Layer</ulink> for your models.
 151                         </para>
 152                     </listitem>
 153
 154                     <listitem>
 155                         <para>
 156                             <emphasis><filename>Bootstrap.php</filename></emphasis>: This file is
 157                             the entry point for your application, and should implement
 158                             <classname>Zend_Application_Bootstrap_Bootstrapper</classname>.
 159                             The purpose for this file is to bootstrap the application and make
 160                             components available to the application by initializing them.
 161                         </para>
 162                     </listitem>
 163                 </itemizedlist>
 164             </listitem>
 165
 166             <listitem>
 167                 <para>
 168                     <emphasis><filename>data/</filename></emphasis>: This directory provides a
 169                     place to store application data that is volatile and possibly temporary. The
 170                     disturbance of data in this directory might cause the application to fail.
 171                     Also, the information in this directory may or may not be committed to a
 172                     subversion repository. Examples of things in this directory are session files,
 173                     cache files, sqlite databases, logs and indexes.
 174                 </para>
 175             </listitem>
 176
 177             <listitem>
 178                 <para>
 179                     <emphasis><filename>docs/</filename></emphasis>: This directory contains
 180                     documentation, either generated or directly authored.
 181                 </para>
 182             </listitem>
 183
 184             <listitem>
 185                 <para>
 186                     <emphasis><filename>library/</filename></emphasis>: This directory is for
 187                     common libraries on which the application depends, and should be on the
 188                     <acronym>PHP</acronym> <property>include_path</property>. Developers should
 189                     place their application's library code under this directory in a unique
 190                     namespace, following the guidelines established in the <acronym>PHP</acronym>
 191                     manual's <ulink
 192                         url="http://www.php.net/manual/en/userlandnaming.php">Userland Naming
 193                         Guide</ulink>, as well as those established by Zend itself. This
 194                     directory may also include Zend Framework itself; if so, you would house it in
 195                     <filename>library/Zend/</filename>.
 196                 </para>
 197             </listitem>
 198
 199             <listitem>
 200                 <para>
 201                     <emphasis><filename>public/</filename></emphasis>: This directory contains all
 202                     public files for your application. <filename>index.php</filename> sets up and
 203                     invokes <classname>Zend_Application</classname>, which in turn invokes the
 204                     <filename>application/Bootstrap.php</filename> file, resulting in dispatching
 205                     the front controller. The web root of your web server would typically be set to
 206                     this directory.
 207                 </para>
 208             </listitem>
 209
 210             <listitem>
 211                 <para>
 212                     <emphasis><filename>scripts/</filename></emphasis>: This directory contains
 213                     maintenance and/or build scripts. Such scripts might include command line,
 214                     cron, or phing build scripts that are not executed at runtime but are part of
 215                     the correct functioning of the application.
 216                 </para>
 217             </listitem>
 218
 219             <listitem>
 220                 <para>
 221                     <emphasis><filename>temp/</filename></emphasis>: The <filename>temp/</filename>
 222                     folder is set aside for transient application data. This information would not
 223                     typically be committed to the applications svn repository. If data under the
 224                     <filename>temp/</filename> directory were deleted, the application should be
 225                     able to continue running with a possible decrease in performance until data is
 226                     once again restored or recached.
 227                 </para>
 228             </listitem>
 229
 230             <listitem>
 231                 <para>
 232                     <emphasis><filename>tests/</filename></emphasis>: This directory contains
 233                     application tests. These could be hand-written, PHPUnit tests, Selenium-RC
 234                     based tests or based on some other testing framework. By default, library code
 235                     can be tested by mimicing the directory structure of your
 236                     <filename>library/</filename> directory. Additionally, functional tests for
 237                     your application could be written mimicing the
 238                     <filename>application/</filename> directory structure (including the
 239                     application subdirectory).
 240                 </para>
 241             </listitem>
 242         </itemizedlist>
 243     </sect1>
 244
 245     <sect1 id="project-structure.filesystem">
 246         <title>Module Structure</title>
 247
 248         <para>
 249             The directory structure for modules should mimic that of the
 250             <filename>application/</filename> directory in the recommended project structure:
 251         </para>
 252
 253         <programlisting language="text"><![CDATA[
 254 <modulename>
 255     configs/
 256         application.ini
 257     controllers/
 258         helpers/
 259     forms/
 260     layouts/
 261         filters/
 262         helpers/
 263         scripts/
 264     models/
 265     services/
 266     views/
 267         filters/
 268         helpers/
 269         scripts/
 270     Bootstrap.php
 271 ]]></programlisting>
 272
 273         <para>
 274             The purpose of these directories remains exactly the same as for the recommended
 275             project directory structure.
 276         </para>
 277     </sect1>
 278
 279     <sect1 id="project-structure.rewrite">
 280         <title>Rewrite Configuration Guide</title>
 281
 282         <para>
 283             <acronym>URL</acronym> rewriting is a common function of <acronym>HTTP</acronym>
 284             servers. However, the rules and configuration differ widely between them. Below are
 285             some common approaches across a variety of popular web servers available at the time of
 286             writing.
 287         </para>
 288
 289         <sect2 id="project-structure.rewrite.apache">
 290             <title>Apache HTTP Server</title>
 291
 292             <para>
 293                 All examples that follow use <property>mod_rewrite</property>, an official
 294                 module that comes bundled with Apache. To use it,
 295                 <property>mod_rewrite</property> must either be included at compile time or
 296                 enabled as a Dynamic Shared Object (<acronym>DSO</acronym>). Please consult the
 297                 <ulink url="http://httpd.apache.org/docs/">Apache documentation</ulink> for your
 298                 version for more information.
 299             </para>
 300
 301             <sect3 id="project-structure.rewrite.apache.vhost">
 302                 <title>Rewriting inside a VirtualHost</title>
 303
 304                 <para>
 305                     Here is a very basic virtual host definition. These rules direct all requests
 306                     to <filename>index.php</filename>, except when a matching file is found under
 307                     the <property>document_root</property>.
 308                 </para>
 309
 310                 <programlisting language="text"><![CDATA[
 311 <VirtualHost my.domain.com:80>
 312     ServerName   my.domain.com
 313     DocumentRoot /path/to/server/root/my.domain.com/public
 314
 315     RewriteEngine off
 316
 317     <Location />
 318         RewriteEngine On
 319         RewriteCond %{REQUEST_FILENAME} -s [OR]
 320         RewriteCond %{REQUEST_FILENAME} -l [OR]
 321         RewriteCond %{REQUEST_FILENAME} -d
 322         RewriteRule ^.*$ - [NC,L]
 323         RewriteRule ^.*$ /index.php [NC,L]
 324     </Location>
 325 </VirtualHost>
 326 ]]></programlisting>
 327
 328                 <para>
 329                     Note the slash ("/") prefixing <filename>index.php</filename>; the rules for
 330                     <filename>.htaccess</filename> differ in this regard.
 331                 </para>
 332             </sect3>
 333
 334             <sect3 id="project-structure.rewrite.apache.htaccess">
 335                 <title>Rewriting within a .htaccess file</title>
 336
 337                 <para>
 338                     Below is a sample <filename>.htaccess</filename> file that utilizes
 339                     <property>mod_rewrite</property>. It is similar to the virtual host
 340                     configuration, except that it specifies only the rewrite rules, and the leading
 341                     slash is omitted from <filename>index.php</filename>.
 342                 </para>
 343
 344                 <programlisting language="text"><![CDATA[
 345 RewriteEngine On
 346 RewriteCond %{REQUEST_FILENAME} -s [OR]
 347 RewriteCond %{REQUEST_FILENAME} -l [OR]
 348 RewriteCond %{REQUEST_FILENAME} -d
 349 RewriteRule ^.*$ - [NC,L]
 350 RewriteRule ^.*$ index.php [NC,L]
 351 ]]></programlisting>
 352
 353                 <para>
 354                     There are many ways to configure <property>mod_rewrite</property>; if you
 355                     would like more information, see Jayson Minard's <ulink
 356                         url="http://devzone.zend.com/a/70">Blueprint for PHP Applications:
 357                     Bootstrapping</ulink>.
 358                 </para>
 359             </sect3>
 360
 361         </sect2>
 362
 363         <sect2 id="project-structure.rewrite.iis">
 364             <title>Microsoft Internet Information Server</title>
 365
 366             <para>
 367                 As of version 7.0, <acronym>IIS</acronym> now ships with a standard rewrite engine.
 368                 You may use the following configuration to create the appropriate rewrite rules.
 369             </para>
 370
 371             <programlisting language="xml"><![CDATA[
 372 <?xml version="1.0" encoding="UTF-8"?>
 373 <configuration>
 374     <system.webServer>
 375         <rewrite>
 376             <rules>
 377                 <rule name="Imported Rule 1" stopProcessing="true">
 378                     <match url="^.*$" />
 379                     <conditions logicalGrouping="MatchAny">
 380                         <add input="{REQUEST_FILENAME}"
 381                              matchType="IsFile" pattern=""
 382                              ignoreCase="false" />
 383                         <add input="{REQUEST_FILENAME}"
 384                              matchType="IsDirectory"
 385                              pattern=""
 386                              ignoreCase="false" />
 387                     </conditions>
 388                     <action type="None" />
 389                 </rule>
 390                 <rule name="Imported Rule 2" stopProcessing="true">
 391                     <match url="^.*$" />
 392                     <action type="Rewrite" url="index.php" />
 393                 </rule>
 394             </rules>
 395         </rewrite>
 396     </system.webServer>
 397 </configuration>
 398 ]]></programlisting>
 399         </sect2>
 400     </sect1>
 401 </appendix>