Installing Propel

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

Prerequisites

Propel runs on most PHP platforms. It just requires:

• PHP 5.2.4+ or newer, with the DOM (libxml2) module enabled
• 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.

Project-Local Installation

For a quick start, the best choice is to install Propel inside a project directory structure, typically under a vendor/ subdirectory: You could install propel manually into the your vendor directory, or let composer do the job for you.

Composer Installation

The only thing you need to do is, to drop the following line into your projects' composer.json file.

{
    "require": {
        "propel/propel1": "~1.6"
    }
}

composer will also take care to download all dependencies which are required by Propel.

Note
Composer requires PHP 5.3.2+. In case you are running PHP5.2.X you should stick to the "Manual Installation"

Manual Installation

myproject/
  ...
  vendor/ <= This is where third-party libraries usually go

To install Propel there using Git, type:

cd myproject/vendor
git clone https://github.com/propelorm/Propel.git propel

This will export the propel library to a local myproject/vendor/propel/ directory.

Alternatively, to use a tarball, type the following commands on unix platforms:

cd myproject/vendor
wget http://files.propelorm.org/propel-1.6.X.tar.gz
tar zxvf propel-1.6.X.tar.gz
mv propel-1.6.X propel

Or, in Windows, download a ZIP from files.propelorm.org, unzip it under the vendor/ directory, and rename it to propel.

Propel Directory Structure

The root directory of the Propel library includes the following folders:

Usually, both the generator and the runtime components are installed on development environments, while the actual test or production servers may need only the runtime component installed.

Installing Dependencies

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

To install these packages, use the PEAR command as follows:

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 PEAR Log.

Testing Propel Installation

The Propel generator component bundles a propel-gen sh script (and a propel-gen.bat script for Windows). This script makes it easy to execute build commands. You can test this component is properly installed by calling the propel-gen script from the CLI:

cd myproject
vendor/propel/generator/bin/propel-gen

The script should output a welcome message, followed by a 'BUILD FAILED' message, which is normal - you haven't defined a model to build yet.

Tip
In order to allow an easier execution the script, you can also add the propel generator's bin/ directory to your PATH, or create a symlink. For example:

cd myproject
ln -s vendor/propel/generator/bin/propel-gen propel-gen # Make a symlink to the propel generator file

Or edit your ~/.bashrc or ~/.zshrc file with :

export PATH=$PATH:/path/to/propel/bin

On Windows you could set the PATH for the opened command with :

set PATH=%PATH%;C:/path/to/propel/generator/bin/

To globally define the PATH adjust it inside the "Environment Variables", which you can find in your system advanced settings panel.

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

Alternative: Global Installation Using PEAR

Alternatively, you can install Propel globally on your system using PEAR. All your projects will use the same Propel version - that may or may not be a good idea, depending on how often you update your projects.

Propel has its own PEAR channel, that you must "discover". Using the pear install -a command, you can let PEAR download and install all dependencies (Phing and PEAR Log).

So the commands to install Propel, Phing and PEAR Log globally sum up to this:

pear channel-discover pear.propelorm.org
pear install -a propel/propel_generator
pear install -a propel/propel_runtime

Once Propel is installed globally, you can access the propel-gen command from everywhere without symlink.

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

pear config-set preferred_state beta

Troubleshooting

PHP Configuration

Propel requires the following settings in php.ini:

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 not be on your PHP include_path. Check the PEAR documentation for details on how to do that.

Phing Version

Phing versions 2.4.3 and 2.4.4 are incompatible with Propel. Check your Phing version by calling:

phing -v

In case you're using a version less than 2.4.5, upgrade to the latest stable version:

pear upgrade phing/phing

Getting Help

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