<!--
-File $Id: Installation.html,v 1.8 2004/11/04 01:46:06 hlellelid Exp $
-License GNU FDL (http://www.gnu.org/copyleft/fdl.html)
-Copyright 2002, Propel project
-Author Hans Lellelid, hide@address.com
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Propel Guide</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link rel="Stylesheet" rev="Stylesheet" href="../css/Documentation.css" type="text/css" media="All" charset="iso-8859-1" />
</head>
<body>
<h1>Installation</h1>
<h2><a name="Installation.Prerequisites"></a>Prerequisites</h2>
<p>In order to install Propel you will need:</p>
<ul>
<li> PHP >= 5.0.0 with XSLT support (--with-xsl on *nix, or enable php_xsl.dll
on Windows)</li>
<li>A supported RDBMS (MySQL, MS SQL Server, PostgreSQL, SQLite, Oracle)</li>
<li><a href="Bibliography.html#bib.phing">Phing 2.0</a></li>
<li><a href="Bibliography.html#bib.creole">Creole</a> >= 1.0.0</li>
<li>PEAR Log package (optional)</li>
</ul>
<p>Propel can be used on both Unix and Windows platforms.</p>
<p>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.</p>
<h2><a name="Installation.PEAR"></a>PEAR Install</h2>
<p>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. </p>
<h3>Generator</h3>
<pre title="pear install generator">
$> pear install http://propel.phpdb.org/pear/propel_generator-current.tgz</pre>
<p>The generator package comes with a convenient propel-gen shell script which
you can use to actually build the project.
<pre title="pear run propel-gen">
$> propel-gen /path/to/your/projectdir [target]</pre>
<p> As you can see in that example, you must create a project directory. You can
look at the the provided sample <em>bookstore</em> project directory (in your
PEAR data directory). This topic is also covered in more detail in the the next
chapter, <a href="GettingStarted.html">Getting Started</a>. </p>
<h3>Runtime</h3>
<p>The runtime classes are installed in the same way as the generator classes.</p>
<pre title="pear install runtime">
$> pear install http://propel.phpdb.org/pear/propel_runtime-current.tgz</pre>
<p>No further configuration is necessary (assuming your PEAR php directory is
on your <em>include_path</em>).</p>
<p><strong>You're done.</strong> Reading the traditional install is probably a
good idea anyway, especially as most examples are written for the traditionally
installed Propel.</p>
<h2><a name="Installation.Conventional"></a>Conventional Install</h2>
<p>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.</p>
<table>
<caption>
Some assumptions for sake of example.
</caption>
<thead>
<tr>
<th>Path </th>
<th>Unix (Linux, FreeBSD, etc.)</th>
<th>Windows</th>
</tr>
<tr>
<td>Propel runtime</td>
<td>/usr/local/propel/runtime</td>
<td>C:\PHP\apps\propel\runtime</td>
</tr>
</thead>
<tbody>
<tr>
<td>Propel generator</td>
<td>/usr/local/propel/generator</td>
<td>C:\PHP\apps\propel\generator</td>
</tr>
<tr>
<td>PEAR libraries</td>
<td>/usr/local/lib/php</td>
<td>C:\PHP\PEAR </td>
</tr>
</tbody>
</table>
<h3>Obtaining</h3>
<p>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.</p>
<h4>Package</h4>
<p>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:</p>
<pre title="unix unpacking">
$> cd /usr/local
$> tar zxvf propel-x.x.x.tar.gz
$> ln -s propel-x.x.x propel
</pre>
<h4>CVS</h4>
<p>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.) </p>
<p>Note: the <em>propel</em> 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 <tt>propel</tt>
directory; also the runtime classes are in the <tt>propel</tt> subdirectory,
while the generator component is in the <tt>propel-generator</tt> directory.
Here's a sample checkout (Unix) using the for-the-sake-of-example paths we defined
above:</p>
<pre title="CVS checkout instructions">
$> cvs -d :pserver:hide@address.com:/cvs login
Password: [guest]
$> cvs -d :pserver:hide@address.com:/cvs checkout propel
$> mkdir /usr/local/propel
$> mv propel/propel /usr/local/propel/runtime
$> mv propel/propel-generator /usr/local/propel/generator</pre>
<p> For Windows users, there are a number of graphical CVS clients available such
as the very capable and easy-to-use <a href="http://www.tortoisecvs.org" target="_blank">TortoiseCVS</a>.</p>
<h3>Setup Environment</h3>
<p>Once you have unpacked your Propel distribution, you need to configure your
PHP environment.</p>
<h4>PHP include_path</h4>
<p>You need to add the <tt>propel/runtime/classes</tt> directory to your PHP include
path. Note that you only need to add the <em>runtime</em> classes to your <em>include_path</em>,
as the build process calculates the <em>include_path</em> 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 <em>include_path</em>
is to simply edit your <tt>php.ini</tt> file and add this directory to the <em>include_path</em>
variable:</p>
<pre title="php.ini settings">
# Unix
include_path="/usr/local/lib/php:/usr/local/propel/classes"
; Windows
include_path="C:\PHP\PEAR;C:\PHP\apps\propel\classes"
</pre>
<p>If you do not have access to the <tt>php.ini</tt> file and cannot specify the <em>include_path</em>
value in your <tt>.htaccess</tt> file, you can always do this at runtime within your PHP scripts:</p>
<pre title="setting include_path at runtime">
<?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');</pre>
<p>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 <em>include_path
</em>to account for your object model PHP classes (i.e. the classes that the
Propel generator builds for you).</p>
<h4>Other INI Variable Recommendations</h4>
<p>You should also check that the following PHP INI settings are correct:</p>
<table>
<caption>
php.ini variables settings
</caption>
<thead>
<tr>
<th>Variable</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr>
<td>ze1_compatibility_mode</td>
<td>Off</td>
</tr>
<tr>
<td><p>magic_quotes_gpc</p></td>
<td><p>Off</p></td>
</tr>
<tr>
<td><p>magic_quotes_sybase</p></td>
<td><p>Off</p></td>
</tr>
<tr>
<td><p>register_globals</p></td>
<td> <p>Off (this doesn't actually affect Propel, but it's important to
note that Propel doesn't need it to be On) </p></td>
</tr>
</tbody>
</table>
<p>These should be the default values for these options. Also, there is no requirement
that <em>register_globals</em> be off, but it is a good idea -- and importantly,
Propel does not require it to be on.</p>
<p>At this point you should be finished installing / setting up Propel. To make
sure it's all working, continue with the <a href="GettingStarted.html">Getting
Started</a> chapter to walk through a sample build.</p>
</body>
</html>