Alex @ Net

This article explains how to install the Propel object persistence layer (known as object-relational mapping, ORM, or data access objects layer, DAO) and related packages (Creole and Phing) for generating data objects and using them in PHP applications.

Object persistence layer provides the developers with the API that allows them to operate with data of the application in object-oriented manner. The developers can use known OOP methods for searching for and restoring the objects from the database. Something like this you can find on the main page of the Propel project and in the Wikipedia article about ORM technology. These enthusiastic words roused my interest in the technology and I promised myself I would spend some time on testing a software for generating object persistence classes. And I ready to try the Propel library, because it is used by the Symphony framework, which I plan to test in a couple of weeks.

Unexpectedly, I experienced a few obstacles during installation and testing the library, especially with configuring related libraries and creating a script for generating a data model. And it was a reason for creating this article, which can save a time of someone, who is trying to install the Propel library.

Before installing Propel, notice that it requires two libraries: Creole and Phing. Creole is a database access layer and is used to generalize the database access. Phing is an automatic build tool, similar to Apache Ant. Both are used by the Propel: with Phing and Creole it generates the data objects, with Creole generated classes reads from and writes to the database. There is no single package with all these libraries, so they should be installed separately and then configured for joint work.

Now I want to introduce organization of my workspace, so you can understand some acpects of installation process and adapt it for your need. First, I do not use the PEAR package manager because I want my applications to be easily deployable. Ideally, I want to copy an application folder to another computer without of bother to installing PEAR on it. Second, PHP CGI is installed in c:\amp\PHP5 folder and uses c:\amp\PHP5\php.ini configuration file. And third, I’m installing server libraries, used by the application, in the folder “libs/server” under the root folder of the application.

There is enough to start with installing Properl and related libraries. Here is the short summary of where you can download the Propel and related libraries and where to find documentation about them:

Download the packages and unpack them to the “libs/server” folder. I prefer to have shortened folder names, so I renamed the “package-X.X.X” folders to just “package”. So the structure of my project is the following:

• libs - a place for the libraries
  
  • server - a place for the server-side libraries
    
    • creole - unpacked Creole package
    • phing - unpacked Phing package
    • propel - unpacked Propel package
• protected - my application resides here
  
  • model - data model of the application

The installation is done and the next my task is to show you how to write a script that generates a persistent data objects. The Propel package includes similar script but it works only when the Creole and the Phing libraries are in the PHP include paths and home folder of the Phing package is in the PATH environment variable of your computer.

Fortunately, the Propel and Phing scripts are configurable—they use environment variables for storing important configuration parameters. Here is a list of the scripts and their variables:

• propel/generator/bin/propel-gen.bat generates PHP classes based on given definition. It calls the phing.bat for executing series of tasks.
  • PROPEL_GEN_HOME specifies path to propel generator home, e.g. “%CD%\..\..\libs\server\propel\generator”.
  • PHING_COMMAND points to the Phing shell script. In our case it will be “%CD%\..\..\libs\server\phing\bin\phing.bat”.
• phing/bin/phing.bat
  • PHP_COMMAND contains the path to the PHP CGI executable, like “c:\amp\php5\php.exe”.
  • PHING_HOME defines where the Phing package is. We can use “%CD%\..\..\libs\server\phing”.
  • PHP_CLASSPATH specifies where the PHP scripts should search for included or required files. This variable should contain paths to the Phing and Creole PHP files.

As you can see, I used %CD% environment variable in the values. This environment variable contains current folder, identical to which the “cd” command returns. This makes possible to create the build script, which does not contain absolute paths, except the path to the PHP executable. Here is an example of such script, located in the “protected/model” folder of the application:

protected/model/build.bat

@ECHO OFF
SET PHP_COMMAND=c:\amp\PHP5\php.exe
SET PHING_HOME=%CD%\..\..\libs\server\phing
SET PHP_CLASSPATH=%PHING_HOME%\classes;%CD%\..\..\libs\server\creole\classes
SET PHING_COMMAND=%CD%\..\..\libs\server\phing\bin\phing.bat
SET PROPEL_GEN_HOME=%CD%\..\..\libs\server\propel\generator
CALL %PROPEL_GEN_HOME%\bin\propel-gen.bat
pause

This script sets the environment variables and executes “propel-gen.bat”, which loads the “build.properties”, “runtime-conf.xml” and “schema.xml” files and generates the corresponded PHP classes. The generated classes will be saved to “build” folder.

To check whether “build.bat” works, you can create the “build.properties”, “runtime-conf.xml” and “schema.xml” files with the content from the Propel documentation/User Guide/Getting Started page, and then run it. The generator should create the “build” folder with files for the specified model. You can examine the system messages, which “build.bat” prints, and check whether they contain errors or not.

PHP 5.1 may show the following warning during build process:


Execution of target "convert-props" failed for the following reason: propel\generator\build-propel.xml:534:12: Cannot write parsed template: Unable to parse template ./templates/conf/Control.tpl: It is not safe to rely on the system's timezone settings. Please use the date.timezone setting, the TZ environment variable or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected 'Europe/Helsinki' for '3.0/DST' instead.

This happens because the current timezone is not specified, neigher in php.ini nor in the PHP script. You can specify the timezone to the PHP executable by adding corresponding command line argument. After that the PHP_COMMAND environment can look like:

SET PHP_COMMAND=c:\amp\PHP5\php.exe -d date.timezone=UTC

Make sure that a build log does not contain the “[propel-sql] Could not perform XLST transformation. Make sure PHP has been compiled/configured to support XSLT.” warning. If so, then you need to enable the php_xsl extension. This extension adds XSLTProcessor class, which supports XSL Transformation. This extension should be enabled only on the system, which generates the object persistence layer—generated classes on the production server do not require this extension.