165 lines
6.4 KiB
Plaintext
165 lines
6.4 KiB
Plaintext
= Installing Propel =
|
|
|
|
[[PageOutline]]
|
|
|
|
Propel is available as a [http://pear.php.net/manual/en/installation.getting.php 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:
|
|
|
|
* [http://www.php.net/ 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.
|
|
|
|
== 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.propelorm.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.
|
|
|
|
{{{
|
|
#!sh
|
|
> pear channel-discover pear.propelorm.org
|
|
> pear install -a propel/propel_generator
|
|
> pear install -a propel/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':
|
|
|
|
{{{
|
|
#!sh
|
|
> pear config-set preferred_state beta
|
|
}}}
|
|
|
|
=== Dependencies for Tarball and Subversion Versions ===
|
|
|
|
The Propel generator uses [http://phing.info/ Phing 2.3.3] to manage command line tasks; both the generator and the runtime classes use [http://pear.php.net/package/Log/ 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:
|
|
|
|
{{{
|
|
#!sh
|
|
> 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.
|
|
|
|
{{{
|
|
#!sh
|
|
> svn checkout http://svn.propelorm.org/branches/1.5 /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.5` 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:
|
|
|
|
{{{
|
|
#!sh
|
|
> cd /usr/local
|
|
> mkdir propel
|
|
> cd propel
|
|
> wget http://pear.propelorm.org/get/propel_generator-1.5.0.tgz
|
|
> tar zxvf propel_generator-1.5.0.tgz
|
|
> wget http://pear.propelorm.org/get/propel_runtime-1.5.0.tgz
|
|
> tar zxvf propel_runtime-1.5.0.tgz
|
|
}}}
|
|
|
|
Once this is done, you'll need to setup your PHP environment to use this library.
|
|
|
|
== Setting Up PHP for the Propel Generator ==
|
|
|
|
The following instructions are only required if you installed Propel from a tarball, or from Subversion.
|
|
|
|
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:
|
|
|
|
{{{
|
|
#!sh
|
|
> /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:
|
|
|
|
{{{
|
|
#!sh
|
|
> cd /usr/local/bin
|
|
> ln -s /usr/local/propel/generator/bin/propel-gen propel-gen
|
|
}}}
|
|
|
|
== Testing Propel Installation ==
|
|
|
|
You can test that the '''Propel generator''' component is properly installed by calling the `propel-gen` script from the CLI:
|
|
|
|
{{{
|
|
#!sh
|
|
> 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
|
|
<?php
|
|
// PEAR installation
|
|
require_once 'propel/Propel.php';
|
|
|
|
// manual installation
|
|
require_once '/usr/local/propel/runtime/lib/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 [wiki:Documentation/1.5/BuildTime Build 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 not be on your PHP `include_path`. Check the PEAR documentation for details on how to do that.
|
|
|
|
=== Getting Help ===
|
|
|
|
If you can't manage to install Propel, don't hesitate to ask for help. See [wiki:Support] for details on getting help.
|