Better PHP Project Layouts

There’s a post up at PHP::Impact about directory structures for web applications. The recommendations are great for a single project on a single domain, but once you get beyond that I think a different approach is called for. First the quick summary, then the expanded text:

• One copy of a library per server, not per project
• Use source control and a build script, rather than manually versioning with directories
• Put your VHosts file in your config/ directory, and link to it with an Apache Include directive
• Multiple webroots per project allows for shared code
• Switch configuration settings against $_SERVER['SERVER_NAME']

If you treat libraries as “children” of your project you have to maintain a different copy of each library for each project on the machine. Versioning nightmare. A better alternative is to have a single, server-wide location for common libraries, and either place this location on the include_path (our approach), or symlink it to the project’s local library folder.

Here’s the standard layout we’ve thrashed out, which is based heavily on Zend’s default layout:

project/
    application/
        controllers/
        models/
        views/
    config/
        httpd-vhosts.conf
        test.project.com.ini
        www.project.com.ini
        admin.project.com.ini
    logs/
        admin.project.com.log
        test.project.com.log
        www.project.com.log
    admin.project.com/
        index.php
    test.project.com/
        index.php
    www.project.com/
        index.php

Use source control and a build script

The key difference is that multiple webroots exist within a single project. In our example we have www (the public-facing site), admin (the control panel) and test (for unit tests). Each webroot contains a front controller, a few static files and some mod_rewrite rules. These sub-domains are held within the same project because they have so much shared code in common (models etc).

The front controller picks up $_SERVER['SERVER_NAME'] and uses that to discover/create its own "{$_SERVER['SERVER_NAME']}.ini” and "{$_SERVER['SERVER_NAME']}.log” files, meaning the build script is trivial.

The httpd-vhosts.conf file contains VHost configurations for each site, and is linked with a simple

Include /srv/project/config/httpd-vhosts.conf

in the httpd.conf. Generating the httpd-vhosts.conf file is pretty much the only thing our build script has to do, but that’s just a matter of setting paths:

<VirtualHost *:80>
    ServerAdmin admin@project.com
    DocumentRoot "/srv/project/www.project.com"
    ServerName www.project.com
    ErrorLog "logs/www.project.com-error_log"
    CustomLog "logs/www.project.com-access_log" common
    php_value include_path ".:/usr/share/zend:/srv/project"
</VirtualHost>

There are some additional links on this subject at the end of PHP::Impact post linked above.