Include PropelORM in a PHP project

PropelORM is an 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.

In this article, I’ll explain how to use PropelORM in an existing PHP project.

Download and installation

If your project is using Git:

  • go to the root of the project:
    cd myproject
  • download Propel as a submodule of your project (if you want to download Propel in myproject/application/plugins/propel):
    git submodule add application/plugins/propel
  • commit the submodule:
    git commit -m "Added PropelORM as a submodule"

If your project doesn’t use Git:

  • go to the subdirectory application/plugins in your project and create a directory propel:
    cd myproject/application/plugins
    mkdir propel
  • download the latest version of PropelORM as a ZIP file or a TAR.GZ file
  • extract the content of the archive in the newly created myproject/application/plugins/propel folder

PropelORM uses a script to generate the mapping code. You have to create a symbolic link to the script in the application directory of your project:

cd myproject/application
ln -s plugins/propel/generator/bin/propel-gen propel-gen


Create a file myproject/application/ which will contain the basic information about the project and DB connection:

cd myproject/application

This file contains:

# Project name
propel.project = project_name
# Connection parameters
propel.database = mysql
# If you want to automatically update the DB, set the following values:
propel.database.url = mysql:host=db_host;dbname=db_name
propel.database.user = db_user
propel.database.password = db_password

DB schema creation

The DB schema is defined in the file myproject/application/schema.xml. You can find on the PropelORM documentation everything you need to build your DB schema: creation of the file and schema format.

Code generation

Once these files are created and contain the correct data, you can use the propel-gen script to generate the mapping source.

To generate the Object Model

cd myproject/application
./propel-gen om

To generate the SQL file

cd myproject/application
./propel-gen sql

To update the DB with the SQL file (need the DB connection info)

cd myproject/application
./propel-gen insert-sql

Runtime connection settings creation

For PropelORM to be able to be linked to the DB when running, you’ll need to create a configuration file that defines the DB connection.

cd myproject/application
touch runtime-conf.xml

This file must contains a configuration like:

<?xml version="1.0" encoding="UTF-8"?>
    <datasources default="project_name">
      <datasource id="project_name">
        <adapter>mysql</adapter> <!-- sqlite, mysql, mssql, oracle, or pgsql -->

The content of the file is described in the PropelORM documentation: Writing The XML Runtime Configuration.

Notice how the id attribute of the <datasource> tag matches the connection name defined in the <database> tag of the schema.xml. This is how Propel maps a database description to a connection.

To build the runtime conf:

cd myproject/application
./propel-gen convert-conf

To run the 3 commands (om, sql, and convert-conf):

cd myproject/application

Including PropelORM in your PHP code

Include in a setup/config file:

// Include the main Propel script
require_once '/path/to/propel/runtime/lib/Propel.php';
// Initialize Propel with the runtime configuration
// Add the generated 'classes' directory to the include path
set_include_path("/path/to/bookstore/build/classes" . PATH_SEPARATOR . get_include_path());

Using PropelORM inside your project

You can find how to use PropelORM on the official documentation.

No tips yet.
Be the first to tip!

Like this post? Tip me with bitcoin!


If you enjoyed reading this post, please consider tipping me using Bitcoin. Each post gets its own unique Bitcoin address so by tipping you're not only making my continued efforts possible but telling me what you liked.

Leave a Reply

Your email address will not be published. Required fields are marked *