<markdown>
===============
Skeleton System
===============

(Note: you can export or checkout a fully operational Solar System from <http://svn.solarphp.com/system/trunk>.)

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


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
 

----------
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 might be 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();
}}


--------------------
Deploying The System
--------------------

You can find a full system ready for checkout or export at <http://svn.solarphp.com/system/trunk>.


Evaluation (LESS SECURE)
========================

Place an SVN checkout, SVN export, or copy of the system directly in your document root, then browse to the top-level `index.php` file.


Production (MORE SECURE)
========================

1. Place an SVN checkout, SVN export, or copy of the system in a secure location on the web server machine (**not** the document root).

2. Delete the top-level `index.php` file (leave alone the `docroot/index.php` in place).

3. Point the web server to the `docroot` directory as its document root (usually using a symlink or a configuration directive).

For example, if place the system at `/home/example/subdomain/system`, you can use Apache directives like the following:

{{code:
    NameVirtualHost *:80
    <VirtualHost *:80>
    	ServerName subdomain.example.com
    	DocumentRoot /home/example/subdomain/system/docroot
    </VirtualHost>
}}
</markdown>