Installing Propel

Propel is available as a  PEAR package, as a "traditional" tgz or zip package, and as a checkout from a Subversion repository. Whatever installation method you may choose, getting Propel to work is pretty straightforward.

Prerequisites

Propel requirements are very light, allowing it to run on most PHP platforms:

•  PHP 5.2.4 or newer, with the following module enabled:
  • XSLT (libxslt)
  • DOM (libxml2)
• A supported database (MySQL, MS SQL Server, PostgreSQL, SQLite, Oracle)

Tip: Propel uses the PDO and SPL components, which are bundled and enabled by default in PHP5.

Propel Components

The Propel library is made of two components: a generator, and a runtime library. These components are not co-dependent, and can be installed independently from each other.

The generator is needed to build the object model, but is not required for running applications that use Propel.

The runtime classes provide the shared functionality that is used by the Propel-generated object model classes. These are necessary to run applications that use Propel to access the database.

Usually, both the generator and the runtime components are installed on development environments, while the actual test or production servers need only the runtime components installed. For your first contact with Propel, just install both.

Installing Propel

Installing Propel From PEAR

In order to install the Propel packages, you must add the pear.phpdb.org channel to your PEAR environment. Once the channel is discovered, you can install the generator package, or the runtime package, or both. Use the '-a' option to let PEAR download and install dependencies.

> pear channel-discover pear.phpdb.org
> pear install -a phpdb/propel_generator
> pear install -a phpdb/propel_runtime

Propel is now installed, and you can test it by following the instructions of the Testing Propel Installation section at the end of this page.

Tip: If you want to install non-stable versions of Propel, change your preferred_state PEAR environment variable before installoing the Propel packages. Valid states include 'stable', 'beta', 'alpha', and 'devel':

> pear config-set preferred_state beta

Dependencies for Tarball and Subversion Versions

The Propel generator uses  Phing 2.2.x to manage command line tasks; both the generator and the runtime classes use  PEAR Log to log events.

If you choose to install Propel via PEAR, these components will be automatically installed as dependencies. If you choose to install Propel from a tarball or a Subversion checkout, you'll have to install them manually:

> pear channel-discover pear.phing.info
> pear install phing/phing
> pear install Log

Refer to their respective websites for alternative installation strategies for Phing and Log.

Installing Propel From Subversion

Installing from SVN trunk ensures that you have the most up-to-date source code.

> svn checkout http://svn.phpdb.org/propel/branches/1.4 /usr/local/propel

This will export both the generator and runtime components to your local propel directory. In addition, you'll also get Propel documentation and unit tests - that's why this method is the preferred installation method for Propel contributors.

Once this is done, you'll need to setup your PHP environment to use this library - see the Setting Up PHP for Propel section below.

Note: branches/1.4 is currently more uptodate code than trunk; trunk is what will become 2.0, however it has had very little work done to it in a long time.

Installing Propel From a Tarball

Download a tarball of each of the Propel components from the Propel website, and uncompress them into the location that best suits your need. For instance, in Linux:

> cd /usr/local
> mkdir propel
> cd propel
> wget http://pear.phpdb.org/get/propel_generator-1.4.0.tgz
> tar zxvf propel_generator-1.4.0.tgz
> wget http://pear.phpdb.org/get/propel_runtime-1.4.0.tgz
> tar zxvf propel_runtime-1.4.0.tgz

Once this is done, you'll need to setup your PHP environment to use this library.

Setting Up PHP for Propel

The following instructions are only required if you installed Propel from a tarball, or from Subversion.

Generator Setup

The Propel generator component bundles a propel-gen sh script (and a propel-gen.bat script for Windows). This script simplifies the commandline invocation of the Propel generator by hiding any references to Phing.

You can call it directly from the command line:

> /usr/local/propel/generator/bin/propel-gen

In order to allow an easier execution the script, you can also:

• add the propel generator's bin/ directory to your PATH,
• or copy the propel-gen script to a location on your PAH,
• or (on Linux systems) create a symlink. For example:

> cd /usr/local/bin
> ln -s /usr/local/propel/generator/bin/propel-gen propel-gen

Runtime Setup

Propel requires that the runtime classes are in PHP include_path.

The easiest and most permanent way to set your include_path is to simply edit your php.ini file and add the propel/runctime/classes/ directory to the include_path variable:

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

or, if you're using Windows,

; Windows
include_path="C:\PHP\PEAR;C:\PHP\apps\propel\runtime\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" . PATH_SEPARATOR . get_include_path());

Now the Propel runtime environment is ready to be used by your object model. As you will learn later, 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).

Note: Only the the runtime classes need to be in the include_path; 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.

Testing Propel Installation

You can test that the Propel generator component is properly installed by calling the propel-gen script from the CLI:

> propel-gen

The script should output a few lines before displaying a 'BUILD FAILED' message, which is normal - you haven't defined a database model yet.

You can test that the Propel runtime component is properly installed by requiring the Propel.php script, as follows:

<?php 
set_include_path("/usr/local/propel/runtime/classes" . PATH_SEPARATOR . get_include_path());

require_once 'propel/Propel.php';
// Propel setup code ... (to be discussed later)

At this point, Propel should be setup and ready to use. You can follow the steps in the Quickstart Guide? to try it out.

Troubleshooting

PHP Configuration

Propel requires the following settings in php.ini:

Variable	Value
ze1_compatibility_mode	Off
magic_quotes_gpc	Off
magic_quotes_sybase	Off

PEAR Directory In Include Path

If you choose to install Propel via PEAR, and if it's your first use of PEAR, the PEAR directory may noit be on your PHP include_path. Check the PEAR documentation for deatils on how to do that.

Getting Help

If you can't manage to install Propel, don't hesitate to ask for help. See Support for details on getting help.