[Solar-talk] Toward a Standard Project Structure

[Paul M Jones]

Hi everyone,

I think I've talked about this before, and want to bring it up again  
for further discussion.

The Vendor library organization ideas are well defined, but often you  
need to collect various libraries under a common structure (call it a  
Project or a Site structure) to include things like source code,  
caches, and so on.  One of the problems with this is how to include an  
SVN external to be able to update it as-needed, but not pollute the  
include-path with other files that the external carries with it.  This  
proposal (based on ideas from Clay Loveless, with hints from Ruby on  
Rails) helps to solve that problem cleanly.

For the example project, we'll say that it uses SVN externals for  
Solar and another library called "Example".  We also need library  
files specific to this project, called "Project" in this example.

These are the main directories, which we will say are in their own SVN  
trunk repository:

     trunk/
         cache/                  # cache files
         config/                 # config files
         docroot/                # web server document root
         include/                # use as the php include_path
         log/                    # log files
         script/                 # command-line scripts
         source/                 # source packages, libraries, etc
         sqlite/                 # sqlite files
         tests/                  # system test files

The "big four" directories here are `source`, `include`, `config`, and  
`docroot`.

The `source` directory is where all your library files and svn  
externals are placed.  This is *not* used as the include-path; it is a  
holding location to keep all your source code in a single location.   
You could also download and extract PEAR-style packages here instead  
of using `pear install` on them.  The `source` directory is organized  
like this:

         source/                 # source packages, libraries, etc
             example/            # svn:external http://example.com/svn/trunk/
                 Example.php
                 Example/
                 bin/
                 docs/
                 tests/
             project/            # libraries for this project
                 Project.php
                 Project/
                 bin/
                 docs/
                 tests/
             solar/              # svn:external http://solarphp.com/svn/trunk/
                 Solar.php
                 Solar/
                 bin/
                 docs/
                 tests/

The `include` directory contains only symlinks to the `source`  
directory.  The `include` directory *is* used as the include-path.   
This means you can have any files at all in the `source` directory and  
not pollute your include-path.  The `include` directory would be  
organized like this:

         include/                # use as the php include_path
             Example.php         # ln -s ../source/example/Example.php
             Example/            # ln -s ../source/example/Example
             Example.php         # ln -s ../source/project/Project.php
             Example/            # ln -s ../source/project/Project
             Solar.php           # ln -s ../source/solar/Solar.php
             Solar/              # ln -s ../source/solar/Solar

Next, we have the `config` directory.  This one holds all  
configuration files for the project, including the Solar config file.

         config/                 # config files
             Solar.config.php

The last of the "big four" directories is the `docroot`.  This is the  
web server document root for the project.  It would be organized as  
follows:

         docroot/                # web server document root
             index.php           # bootstrap file
             public/             # public assets
                 Example/        # ln -s ../../source/example/Example/ 
App/Public
                 Project/        # ln -s ../../source/project/Project/ 
App/Public
                 Solar/          # ln -s ../../source/solar/Solar/App/ 
Public

Because of the standardized project structure, the index.php file  
knows where everything is for the project. It might be set up  
something like this:

{{code: php
     // project trunk directory
     $trunk = dirname(dirname(__FILE__));

     // set the include-path
     set_include_path(".:..:$trunk/include");

     // load and start Solar with the config file
     require_once 'Solar.php';
     Solar::start("$trunk/config/Solar.config.php");

     // instantiate and run the front controller
     $front = Solar::factory('Solar_Controller_Front');
     $front->display();

     // Done!
     Solar::stop();
}}

I think the other directories are self-explanatory.

Please let me hear your comments and criticism of this structure as a  
standard for Solar projects.  In particular, will this work on non- 
Unix-like (i.e., Windows) systems?

Thanks guys.


-- pmj