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:

<?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();
?>