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:

<?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:

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