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
docroot/. The others are mostly self-explanatory.
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.)
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.
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 ...
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.
include/ directory is organized like
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.
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
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
public/ subdirectory contains public assets
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.
public/ subdirectory is organized as
docroot/ index.php # bootstrap file public/ # public assets Solar/ # View/ # Helper/ # Pager/ # ln -s
If you create class with a
for public assets, you can use the link-public
command to automatically create these symlinks (both Windows Vista
and Unix symlinks are supported).