[Solar-talk] Toward a Standard Project Structure

[Kilbride, James P.]

Do we really want to put the application source(Vendor/App/Whatever) in
the actual web doc root? I personally think it's a really good idea to
keep that out of the web doc root and in the source directory and then
setting up different index.php files in the doc root for each one that
calls a different solar.config.php file in the config directory.. unless
I'm missing something here.

James Kilbride 

-----Original Message-----
From: solar-talk-bounces at lists.solarphp.com
[mailto:solar-talk-bounces at lists.solarphp.com] On Behalf Of Paul M Jones
Sent: Friday, February 29, 2008 9:49 AM
To: solar-talk at lists.solarphp.com
Subject: [Solar-talk] Toward a Standard Project Structure

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
_______________________________________________
Solar-talk mailing list
Solar-talk at lists.solarphp.com
http://mailman-mail3.webfaction.com/listinfo/solar-talk