Installation

Prerequisites

In order to install Propel you will need:

Propel can be used on both Unix and Windows platforms.

Propel is available in a "traditional" tarball format and as of version 1.0.0 is also available as a PEAR-installable package. The tarball option gives more flexibility, but is more difficult to install. The PEAR option is perfect if you want to get up and running quickly, but it is more "magical" and hence the learning curve for customizations is steeper.

PEAR Install

It is now possible to install both the Propel generator and runtime components as PEAR packages. This is by far the easiest way to get Propel running, but may not be quite as easy to configure as the more traditional install. These packages actually do not depend on each other, so you can install only the generator or only the runtime classes. Note that the runtime classes do depend on the Creole package.

Generator

$> pear install http://propel.phpdb.org/pear/propel_generator-current.tgz

The generator package comes with a convenient propel-gen shell script which you can use to actually build the project.

$> propel-gen /path/to/your/projectdir [target]

As you can see in that example, you must create a project directory. You can look at the the provided sample bookstore project directory (in your PEAR data directory). This topic is also covered in more detail in the the next chapter, Getting Started.

Runtime

The runtime classes are installed in the same way as the generator classes.

$> pear install http://propel.phpdb.org/pear/propel_runtime-current.tgz

No further configuration is necessary (assuming your PEAR php directory is on your include_path).

You're done. Reading the traditional install is probably a good idea anyway, especially as most examples are written for the traditionally installed Propel.

Conventional Install

For the sake of simplicity this chapter will make some assumptions about file locations. We assume your setup will probably differ, so these should just serve as a reference for the instructions that follow.

Some assumptions for sake of example.
Path Unix (Linux, FreeBSD, etc.) Windows
Propel runtime /usr/local/propel/runtime C:\PHP\apps\propel\runtime
Propel generator /usr/local/propel/generator C:\PHP\apps\propel\generator
PEAR libraries /usr/local/lib/php C:\PHP\PEAR

Obtaining

You can install Propel from a released package (or snapshot distribution) or from CVS. Installing from a release or snapshot will always be simpler, but if you would like to keep up with and (hopefully!) help with Propel development, then you should checkout a copy of the source from CVS.

Package

If you obtained a tar.gz or .zip of Propel, then you can simply uncompress the archive and move the resulting folder to the right location. For example:

$> cd /usr/local

$> tar zxvf propel-x.x.x.tar.gz

$> ln -s propel-x.x.x propel

CVS

Installing from CVS ensures that you have the most up-to-date source code. (Of course CVS code is not stable and should not be used in production.)

Note: the propel module in CVS has a slightly different directory structure due to legacy considerations and limitations imposed by tigris.org. Notably, all "modules" are actually in a top-level propel directory; also the runtime classes are in the propel subdirectory, while the generator component is in the propel-generator directory. Here's a sample checkout (Unix) using the for-the-sake-of-example paths we defined above:

$> cvs -d :pserver:guest@cvs.tigris.org:/cvs login
  Password: [guest]

$> cvs -d :pserver:guest@cvs.tigris.org:/cvs checkout propel
$> mkdir /usr/local/propel

$> mv propel/propel /usr/local/propel/runtime

$> mv propel/propel-generator /usr/local/propel/generator

For Windows users, there are a number of graphical CVS clients available such as the very capable and easy-to-use TortoiseCVS.

Setup Environment

Once you have unpacked your Propel distribution, you need to configure your PHP environment.

PHP include_path

You need to add the propel/runtime/classes directory to your PHP include path. Note that you only need to add the runtime classes to your include_path, as the build process calculates the include_path for the generator classes automatically. In other words, this step is not required to build your object model, but it is required to actually use your generated code from a PHP script. The easiest and most permanent way to set your include_path is to simply edit your php.ini file and add this directory to the include_path variable:

# Unix
include_path="/usr/local/lib/php:/usr/local/propel/classes"

; Windows
include_path="C:\PHP\PEAR;C:\PHP\apps\propel\classes"

If you do not have access to the php.ini file and cannot specify the include_path value in your .htaccess file, you can always do this at runtime within your PHP scripts:

<?php 

set_include_path("/usr/local/propel/runtime/classes:" . get_include_path());

require_once 'propel/Propel.php';
Propel::init( MY_CONF_DIR . '/propel/runtime-conf.php');

Now the Propel runtime environment is ready to be used by your object model. As you will learn in subsequent sections, you will also need to modify the include_path to account for your object model PHP classes (i.e. the classes that the Propel generator builds for you).

Other INI Variable Recommendations

You should also check that the following PHP INI settings are correct:

php.ini variables settings
Variable Value
ze1_compatibility_mode Off

magic_quotes_gpc

Off

magic_quotes_sybase

Off

register_globals

Off (this doesn't actually affect Propel, but it's important to note that Propel doesn't need it to be On)

These should be the default values for these options. Also, there is no requirement that register_globals be off, but it is a good idea -- and importantly, Propel does not require it to be on.

At this point you should be finished installing / setting up Propel. To make sure it's all working, continue with the Getting Started chapter to walk through a sample build.