Using Propel ORM with Smarty templates in a PHP project – Part 1

Recently I decided to switch a project from ASP.NET to PHP and in order to ease my development I decided to use two interesting libraries:

  • Smarty – a template engine for PHP, facilitating the separation of presentation (HTML/CSS) from application logic. This implies that PHP code is application logic, and is separated from the presentation.
  • Propel ORM – open-source Object-Relational Mapping (ORM) for PHP5. It allows you to access your database using a set of objects, providing a simple API for storing and retrieving data.

This is the first part (out of 2) of the article which will focus on explaining how to install both libraries and use them in your PHP project, how to generate the Propel classes for working with an existing MySQL database, configure and initialize Propel for you website and finally, display data from your database using the Smarty library.

This part will focus on Propel ORM framework, how to install it and use it in a project for which you have already a MySQL database. So, without further delay, let’s get started with Propel…

1. Installing Propel ORM

First step we need to do is download and install the latest Propel ORM version. To download the latest version of Propel ORM you can access the Download page of the project and choose any of the options that fits you better. I downloaded the latest full propel package – version 1.5.6.

In order to use Propel ORM, you don’t need to actually run any installer, you just need to unzip the contents of the archive in a location convenient for you. Before you can run Propel ORM generator you will need to:

  • download the Phing library which is used by Propel ORM
  • after you download Phing, make sure that phing.bat and also php.exe can be found on your PATH environment variable. I had to add to my PATH both the location for phing.bat and php.exe in order to be able to run the Propel generator.

2. Generating the schema.xml file from your existing MySQL database

For the demo purposes of this article we’ll use a very simple MySQL database with a single table name people with the following structure:

    CREATE TABLE `people` (
      `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
      `name` varchar(30) NOT NULL,
      `age` int(3) unsigned NOT NULL,
      PRIMARY KEY (`id`)
    ) ;

The first step in using Propel ORM with an existing database is to generate the schema.xml file from our existing database. For that we need to create a folder on the disk where we’ll store all the Propel generated files (om classes, configuration files). For convenience I created my PropelTest folder inside my propel\generator\bin folder. In order to generate the schema.xml file we first need to create a file which I placed inside the PropelTest folder I just created. The file looks like this:

propel.project = PropelTest

# The Propel driver to use for generating SQL, etc.
propel.database = mysql

# This must be a PDO DSN
propel.database.url = mysql:dbname=PropelTest
propel.database.user = root
# propel.database.password =

Once you have the file you can run the propel-gen command. I did it from the propel\generator\bin folder:

> propel-gen PropelTest reverse

The first argument of the command is the folder in which we have the file. If the setup of Propel and Phing was done properly, the above command should work properly. If you have any errors try to fix them (I had few errors in the beginning and the error messages were pretty clear).

Once you run successfully the above command you should see in the PropelTest folder a new file: schema.xml

If you are curious to open it in any text editor, you will see the database definition:

  1. <?xml version="1.0" encoding="utf-8"?>
  2. <!--Autogenerated by PropelSchemaReverseTask class.-->
  3. <database name="PropelTest" defaultIdMethod="native">
  4. <table name="people" phpName="People">
  5. <column name="id" phpName="Id" type="INTEGER" size="11" primaryKey="true" autoIncrement="true" required="true"/>
  6. <column name="name" phpName="Name" type="VARCHAR" size="30" required="true"/>
  7. <column name="age" phpName="Age" type="INTEGER" size="3" required="true"/>
  8. </table>
  9. </database>

3. Generating the model classes

Once we have the schema.xml file, we can generate the model classes we will use in your project to work with the database. In order to generate the classes we need to run the following command:

> propel-gen PropelTest om

If the command finishes running successfully, in the PropelTest folder you created you should see a new folder called build, which also contains a folder called classes. In the classes folder you should find another folder which you can use in you project. The name of this folder is given by the propel.project value in the file. In our case it’s again PropelTest.

For every table in the database, Propel creates 3 PHP classes:

  • a model class (e.g. People), which represents a row in the database;
  • a peer class (e.g. PeoplePeer), offering static constants and methods mostly for compatibility with previous Propel versions;
  • a query class (e.g. PeopleQuery), used to operate on a table to retrieve and update rows

More details on the model classes can be found here.

4. Generating the Propel initialization file

Once we have generated the model classes we have one step left to perform before actually using them in our project: we need to generate an initialization file for Propel framework. In order to generate our initialization file we’ll need to create one XML file named runtime-conf.xml which should look like this:

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <config>
  3. <propel>
  4. <datasources default="PropelTest">
  5. <datasource id="PropelTest">
  6. <adapter>mysql</adapter> <!-- sqlite, mysql, myssql, oracle, or pgsql -->
  7. <connection>
  8. <dsn>mysql:host=localhost;dbname=PropelTest</dsn>
  9. <user>root</user>
  10. <password></password>
  11. </connection>
  12. </datasource>
  13. </datasources>
  14. </propel>
  15. </config>

According to the Propel documentation, the id  attribute for the datasource element must have the same value as the name attribute of the database element from schema.xml file. You can find more details about the runtime configuration file here.

Once you created the runtime-conf.xml file you can run the following command:

> propel-gen PropelTest convert-conf

After running this command, if you didn’t get any errors, you should see in the build folder a new folder called conf. In the new folder you should find your initialization file which in my case has the name PropelTest-conf.php.

5. Using Propel in your PHP project

In order to use Propel in my PHP project I created two additional folders in my project:

  • model – folder in which I copied the content of the build folder generated running the previous steps. If you’ll decide to do the same, in the model folder you’ll have the classes and conf folder with their contents.
  • propel – folder in which I copied the contents of the runtime\lib folder from the Propel installation.

Next step was to create a setup script for Propel which I am including in all the PHP scripts which need to access the database.

The setup script is very simple and looks like this:

  1. <?php
  2. // Include the main Propel script
  3. require_once 'propel/Propel.php';
  5. // Initialize Propel with the runtime configuration
  6. Propel::init("model/conf/PropelTest-conf.php");
  8. // Add the generated 'classes' directory to the include path
  9. set_include_path("model/classes" . PATH_SEPARATOR . get_include_path());
  10. ?>

6. Adding, updating and deleting entries in the database with Propel

Once you generated the model classes, using them and interacting with the database is rather simple.

In order to show how to create, update and delete an entry for the people table from our database, I just created a simple PHP script which does all the operations mentioned before. The script is just for demo purpose, I am sure that for your projects you’ll get to use more complex queries.

The demo script is:

  1. <?php
  2. include("propel_init.php");
  4. function PrintDetails($people, $message)
  5. {
  6. print $message."<br />ID: ".$people->getId()."<br />Name: ".$people->getName()."<br />Age: ".$people->getAge()."<br /><br />";
  7. }
  9. // create a new record
  10. $me = new People();
  11. $me->setName('Andrei');
  12. $me->setAge(28);
  13. $me->save(); // save the record to the table
  15. PrintDetails($me, "Created:");
  17. // update the entry
  18. $people = PeopleQuery::create()->findPK(2); // find the people record with the Primary Key 1
  19. if($people != null)
  20. {
  21. PrintDetails($me, "Found:");
  22. $people->setName('Andrei Croitoriu');
  23. $people->save();
  24. PrintDetails($people, "Updated found entry to:");
  26. $people->delete();
  27. print "Deleted the entry!";
  28. }
  29. ?>

For more details on the basic CRUD operations with Propel you can read this page.

I’ll stop here with this part of the article, hoping that the steps listed above with the explanations given will be enough to get you started with Propel. I know that the example given is very simple, but should be enough to make your understand how to use Propel.

In the following article (part 2 of this one) I will explain in a similar way how to get started with Smarty (at a very low level) and also how to use MySQL views with Propel to display data in your project.

In case you have any comments, questions and any sort of feedback for this article, please feel free to drop me a message.

Happy coding!