A.6. Project System
Prev  Appendix A. Project Standards  Next

A.6. Project System

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 your project.

These are the main files and directories in a Solar system: 

SYSTEM/
    index.php               # quick-start (insecure) bootstrap
    config.php              # main config file
    config/                 # other config files
    docroot/                # web server document root
        .htaccess           # mod-rewrite rules
        index.php           # real bootstrap file
        public/             # public assets
            Solar/          # Solar assets
    include/                # used as the php include_path
    script/                 # command-line scripts
        solar               # the solar command-line tool
    source/                 # source packages, libraries, etc
    sqlite/                 # sqlite files
    tmp/                    # temp files
        cache/              # private cache
        log/                # log files
        mail/               # test emails
        session/            # session files

The "big four" directories here are source/, include/, config/, and docroot/. The others are mostly self-explanatory.

A.6.1. The source/ Directory

The source/ directory is where all your source files are placed, including the files from make-vendor. This is *not* used as the include-path; it is a holding location to keep all your source code in one place. (We will get to the include-path shortly.)

The source/ directory doesn't care what kind of code or pacakges you keep there. You can download and extract PEAR-style packages, keep downloads of third-party libraries, or use svn externals or git clones. You could even keep multiple versions of the same libraries here, so long as each gets its own subdirectory.

The source/ directory is organized like this: 

source/
    acme/               # libraries from the `make-vendor Acme` CLI call
        Acme.php
        Acme/
        config/
        script/
        docs/
        tests/
    example/            # svn:externals http://svn.example.com/trunk
        ...
    solar/              # core Solar libraries
        Solar.php
        Solar/
        config/
        script/
        docs/
        tests/
    third-party/        # copied or downloaded from a third party
        ...

A.6.2. The include/ Directory

The include/ directory is used as the include-path for your Solar system code. In general, the include/ directory contains only symlinks to the source/ directory. This means you can have any files at all in the source/ directory and not pollute your include-path. It also means you can swap between sources at will by pointing the symlink to whatever you want.

The include/ directory is organized like this: 

include/
    Acme.php            # ln -s ../source/acme/Acme.php
    Acme/               # ln -s ../source/acme/Acme
    Example/            # ln -s ../source/Example
    Solar.php           # ln -s ../source/solar/Solar.php
    Solar/              # ln -s ../source/solar/Solar
    thirdparty.php      # ln -s ../source/third-party/some_file.php

If you use make-vendor, these links will be created for you automatically (both Windows Vista and Unix style symlinks are supported). If you bring in your own sources from Solar-style vendors, you can use link-vendor to create them for you. For non-Solar-style vendors, you will need to create the links yourself.

A.6.3. The config/ Directory

Next, we have the config/ directory. This one holds all configuration files for the system. 

config.php
config/
    access.txt          # an example ACL file
    htpasswd.conf       # an example password file
    thirdparty.ini      # a .ini file for a third-party library

A.6.4. The docroot/ Directory

The last of the "big four" directories is the docroot/. This is the web server document root for the system; your virtual host configurations should point to this directory, not to the SYSTEM root.

The public/ subdirectory contains public assets such as Javascript files, stylesheets, images, etc. In a Solar-style vendor, the ending directories are actually symlinks back to a Public/ directory for a particular class. This lets you distribute public assets along with the class package without having to copy those assets every time you change them.

The public/ subdirectory is organized as follows: 

docroot/
    index.php               # bootstrap file
    public/                 # public assets
        Solar/              # 
            View/           # 
                Helper/     # 
                    Pager/  # ln -s SYSTEM/source/Solar/View/Helper/Pager/Public

If you create class with a Public/ subdirectory for public assets, you can use the link-public command to automatically create these symlinks (both Windows Vista and Unix symlinks are supported).

Prev  Up  Next
A.5. Universal Configuration  Home  Appendix B. Naming Conventions

Local