<markdown>
============
Solar System
============

---------------
Overview
---------------

The library organization for Solar and your Vendor files is good for the core of the application, but usually you will need to deploy those libraries, as well as libraries from other Vendors, to a web server or other target machine.  That means we need a common level of organization for the various support files and SVN externals; we call this a Solar "system".

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

-----------
Directories
-----------

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

    trunk/
        config/                 # config files
        docroot/                # web server document root
        docs/                   # system documentation
        include/                # used as the php include_path
        script/                 # command-line scripts
        source/                 # source packages, libraries, etc
        sqlite/                 # sqlite files
        tests/                  # system test files
        tmp/                    # temp files
            cache/              # private cache
            log/                # log files
            session/            # session files
            
The "big four" directories here are `source`, `include`, `config`, and `docroot`.  The others are mostly self-explanatory.


Source
======

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:externals http://example.com/svn/trunk/
                Example.php
                Example/
                script/
                docs/
                tests/
            vendor/             # libraries from the system vendor
                Vendor.php
                Vendor/
                script/
                docs/
                tests/
            solar/              # svn:externals http://solarphp.com/svn/trunk/
                Solar.php
                Solar/
                script/
                docs/
                tests/
     
     
Include
=======

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
            Vendor.php          # ln -s ../source/vendor/Vendor.php
            Vendor/             # ln -s ../source/vendor/Vendor
            Solar.php           # ln -s ../source/solar/Solar.php
            Solar/              # ln -s ../source/solar/Solar
      

Config
======

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

        config/                 # config files
            Solar.config.php    # Solar config file


Docroot
=======

The last of the "big four" directories is the `docroot`.  This is the web server document root for the system.  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
                Vendor/         # ln -s ../../source/vendor/Vendor/App/Public
                Solar/          # ln -s ../../source/solar/Solar/App/Public
 

----------------------
Bootstrap (Index) File
----------------------

Because of the standardized system structure, the `index.php` file knows where everything is for the system. In theory, you should be able to use the same index file code in any system, and leave the specifics of setup in the config file.  The index file is set up something like this:

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

    // set the include-path
    set_include_path("$system/include");

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

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

    // Done!
    Solar::stop();
}}
</markdown>