Chapter 2. Installation

This chapter explains how to install the PHOCOA framework on your system.

2.1. Framework Installation


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:

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 install phing/phing

pear channel-discover
pear install Horde/Yaml

pear channel-discover
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

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


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

$ 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.