This is a tutorial on how to integrate Propel with DooPHP, giving you the power of an extremely fast and easy to use PHP MVC framework together with a powerful ORM.

You will discover how easy it is to integrate a third-party ORM library with DooPHP, and you should be able to use this as a model to integrate other libraries with your DooPHP project.

Step 1 – Directory structure

In DooPHP, all code should go into a ‘protected’ directory. This can be held within or outside your normal web path. I normally create it within my web path but protect the directory through .htaccess or Nginx configuration.

Next, you create a directory called protected/orm – all your Propel configuration goes in there.

Step 2 – build.properties

You will need to define a build.properties file in the orm directory. I presume you know how to create Propel configuration and schema files as this tutorial only concentrates on making Propel work with DooPHP.

The important parts of build.properties for this tutorial are as follows:

propel.project = my_propel_project
propel.output.dir = ${propel.project.dir}/../model/propel
propel.php.dir = ${propel.output.dir}/classes
propel.phpconf.dir = ${propel.output.dir}/conf
propel.sql.dir = ${propel.project.dir}/sql

This will ensure the classes themselves go into a directory calles protected/model/propel so you can easily keep them apart from your own DooPHP models, whilst the generated SQL goes into protected/orm/sql.

Step 3 – Set default Propel configuration options

Define the path to Propel runtime as well as the name of the project in your protected/config/common.conf.php file:

$config['propel_path'] = $config['SITE_PATH'] . 'protected/class/propel-runtime-1.6/';
$config['propel_default_project'] = 'my_propel_project';

I store the Propel runtime with each individual project, in the class directory with all my other classes – but just in case I want it stored elsewhere the path is defined above.

Where does the Propel Default Project name come from? It’s taken from the “propel.project = my_propel_project” configuration in build.properties in Step 2 above.

Step 4 – Create a Propel loader class

Store this as protected/class/InitPropel.php:

<?php
/*
 * Copyright (C) 2011 I B Resources. All rights reserved.
 * Released for use in any personal or commercial project.
 * No attribution required, but link to
 * http://www.ibresources.com/ would be appreciated.
 */

// Include the main Propel script
require_once(Doo::conf()->propel_path . 'Propel.php');

class InitPropel {

  static $_propelLoaded = false;

  /**
   *
   * Initialise Propel
   *
   * Format:
   *   InitPropel::init();
   *
   * @static
   * @return bool
   */
  static public function init($dataSource = null) {

    if (self::$_propelLoaded) {
      return false;
    }

    if (!Propel::isInit()) {
      // Initialize Propel with the runtime configuration
      Propel::init(Doo::conf()->SITE_PATH . "protected/model/propel/conf/{$dataSource}-conf.php");
      set_include_path(Doo::conf()->SITE_PATH . "protected/model/propel/classes/" . PATH_SEPARATOR . get_include_path());
    }
    self::$_propelLoaded = true;
    return true;
  }

}

InitPropel::init(Doo::conf()->propel_default_project);

Step 5 – Call it in your code

Using Propel now becomes very easy. Just call the class in your controller:

class AdminController {

  public function listUsers() {
    Doo::loadClass('InitPropel');

    // Next bit assumes you have a 'user' table definition, of course!
    $users = UserQuery::create()
               ->find();
  }

}

You can also load the class in beforeRun so you don’t have to call it in every function in your controller.