Chapter 2. Installation
This chapter explains how to install the PHOCOA framework on your system.
2.1. Framework Installation
Dependencies
PHOCOA depends on many other great projects. Some of these are optional, and some are required. PHOCOA works best if the following are installed on your system:
PHP 5.2.x+
phing
Smarty
PEAR::Log, PEAR::Mail, PEAR::Mail_Mime, PEAR::Net_SMTP
A YAML parser - either Horde/Yaml, or syck (great installation instructions herel)
Propel 1.2 or 1.3b4+
PhpDocumentor
Below is a quick reference for installing these dependencies. For complete details, see Appendix A.
Installing PHP5 is beyond the scope of this documentation.
You can install many of PHOCOA's dependencies with pear:
pear install Log Mail Mail_Mime Net_SMTP PhpDocumentor pear channel-discover pear.phing.info pear install phing/phing pear channel-discover pear.horde.org pear install Horde/Yaml pear channel-discover pear.phpdb.org pear config-set preferred_state beta pear install phpdb/propel_generator phpdb/propel_runtime
To install smarty, follow the directions from the Smarty web site on a smarty package you download.
Where to Install Dependencies
Depending on where you install your non-PEAR dependencies (Smarty, etc), you need to tweak the PHP include_path setting to ensure that PHOCOA can see all of your dependencies.
PHOCOA assumes that things are installed in PEAR-like directory structures. That is, PHOCOA will look for propel via require('propel/Propel.php'), and assume that there is a directory propel with the propel code in your include path.
The best way to set up non-PEAR dependencies is to create a directory somewhere called "phplib", and in that folder, put all of your dependencies:
$ ls -1 /opt/phplib propel smarty
Then, edit the include_path in webapp.conf to include /opt/phplib.
Propel Integration
Propel is PHOCOA's equivalent of Core Data. Propel allows you to model your data objects in a simple format, automatically handles database retrieval and persistence, and provides you with a place to add custom business logic to your model.
 | One minor modification needs to be made to the Propel code to work with PHOCOA. See Appendix B for instructions. A similar change would need to be made for any other ORM you would want to use. |
| PHOCOA works best with Propel 1.3. You can use 1.2, but you have to manage your own Propel class autoloading and some code-gen capabilities have not been tested. |
| Although PHOCOA includes support for Propel out-of-the-box, the two projects are very loosely coupled. You could theoretically use any PHP ORM/DB solution with PHOCOA. |
The PHOCOA framework is contained in its own directory. Your PHOCOA-based web application will live in its own directory, separate from the framework code. This makes it easy to keep the two separated for purposes of backup, upgrading, etc.
| Eventually we will create a pear channel for installing phocoa. |
PHOCOA Directory Structure
First let's install the PHOCOA framework. Unpack the PHOCOA tarball. The directory structure looks like:
$ ls -l phocoa/ total 0 drwxr-xr-x 4 alanpins staff 136 Aug 2 10:34 classes drwxr-xr-x 5 alanpins staff 170 Oct 15 16:53 conf drwxr-xr-x 7 alanpins staff 238 Oct 17 14:57 docs drwxr-xr-x 34 alanpins staff 1156 Oct 17 13:57 framework drwxr-xr-x 9 alanpins staff 306 Oct 16 12:04 modules drwxr-xr-x 6 alanpins staff 204 Oct 15 16:50 phing drwxr-xr-x 4 alanpins staff 136 Aug 2 10:33 skins drwxr-xr-x 5 alanpins staff 170 Aug 2 10:33 smarty drwxr-xr-x 5 alanpins staff 170 Aug 2 10:34 wwwroot
The classes directory contains a skeleton of the basic application infrastructure needed to have a functional application. This will be copied to your application's modules directory during install.
The conf directory contains default versions of all configuraiton files. These will be copied to your application's conf directory during install.
The docs directory contains a complete PHPDoc API reference for the framework. Once you have PHOCOA installed, this can be reached from http://your-server.com/docs.
| The docs directory shipped with PHOCOA does not include built documentation. Use PHPDOC to build the docs with the following command. Eventually, this will be set up as a Phing task. The docs are also available online at http://phocoa.com/docs/. $ cd phocoa $ phpdoc -dn framework-base -t docs/phpdocs -ti "PHOCOA Documentation" -o HTML:frames:default \ --ignore test/ -d framework -f "smarty/plugins/*" -f "conf/webapp.conf" |
The framework directory contains most of the framework's code.
The modules directory contains modules that are used by the core framework, or are bundled with the framework.
The phing directory contains the phing buildfiles for PHOCOA.
The skins directory contains bundled skins. This is just a single skin, so that your application has some skin when it starts. These will be copied to your application's skins directory during install.
The smarty directory is where templates and plugins used by the framework go.
The wwwroot directory is the public wwwroot. This wwwroot contains the bootstrapping code for a PHOCOA application and a directory for all public www documents.