Propel Your PHP Applications
Hans Lellelid
International PHP Conference
2007-11-06

Introduction
• My name is Hans Lellelid
• Developer + manager at Applied Security,
Inc. (near Washington DC).
• I wrote/ported original Propel.
• I currently manage the project with David
Zülke – and an ever-growing team of
developers.
Hans Lellelid: Propel Your PHP Applications 2

This Talk
• Overview of Propel
• A typical work cycle
• More in-depth usage
• Advanced features
• Slides available at
http://propel.phpdb.org/presentations/
Hans Lellelid: Propel Your PHP Applications 3

Pre-Flight Check
Going over the basics.
Hans Lellelid: Propel Your PHP Applications 4

Fact Sheet
• Propel is an ORM tool for PHP5.
– It is also a code (and DDL) generator.
• Based on Apache Torque.
• Includes runtime and generator
frameworks.
• Uses PDO (v1.2 uses Creole)
• Generator uses Phing tasks to create the
PHP and SQL files.
• Installs using PEAR installer.
Hans Lellelid: Propel Your PHP Applications 5

ORM Patterns in PHP
• The most common alternative ORM pattern
in PHP is ActiveRecord.
– (Thank you, Ruby on Rails!)
• Propel is not an ActiveRecord
implementation: it is a Row Data Gateway
+ Table Data Gateway implementation.
• Key differences:
– Clean division of labor between table
operation objects and row instances.
– RDG and TDG are inherently simpler, more
transparent, models.
Hans Lellelid: Propel Your PHP Applications 6

Motivations & Purpose
• Created because nothing comparable
existed for PHP at the time.
• Designed to facilitate prototyping and RAD
• Basic Philosophy: Database tasks should
feel as simple as they actually are.
• Designed for “enterprise” frameworks.
Hans Lellelid: Propel Your PHP Applications 7

Requirements
• PHP 5
– Version 1.3 requires PHP >= 5.2
– SPL, PDO (1.3), XML, XSLT
• Phing
• A supported database. Currently Propel
supports: MySQL, PostgreSQL, MSSQL,
Oracle, SQLite
Hans Lellelid: Propel Your PHP Applications 8

Propel will ...
• Generate classes to represent your
database (model) in an OOP way.
– “Object” classes for rows (RDG)
– “Peer” classes for table operations (TDG)
• Build SQL (DDL) to initialize your database.
• Use unit-of-work pattern to wrap nested
inserts in transactions.
• Provide Exception-based error handling.
• Allow you to avoid SQL (if you want).
• Type-cast output and escape input.
Hans Lellelid: Propel Your PHP Applications 9

But Propel won't ...
• Build forms, reports, or other display stuff.
– Several full frameworks are built around
Propel to provide this (e.g Symfony, Agavi)
• Help you design your database.
• Prevent you from writing insecure code.
• Replenish essential electrolytes after a hard
workout.
Hans Lellelid: Propel Your PHP Applications 10

Flight Plan
A Typical Propel Work Cycle
Hans Lellelid: Propel Your PHP Applications 11

A Typical Workflow
• Design Database in XML (schema.xml)
• Configure generator (build.properties)
• Configure runtime (runtime-conf.xml)
• Build SQL DDL and PHP classes.
• (Maybe) initialize database.
• Use newly-built objects in your application.
Hans Lellelid: Propel Your PHP Applications 12

schema.xml
• The schema.xml is the single authority for
your data model.
• Written in [quite intuitive] XML
<?xml version=\"1.0\"?>
<database name=\"demo\">
<table name=\"session\">
<column name=\"id\" type=\"integer\" primaryKey=\"true\" />
<column name=\"name\" type=\"varchar\" size=\"255\" />
<column name=\"room\" type=\"varchar\" size=\"16\" />
<column name=\"speaker\" type=\"varchar\" size=\"32\" />
</table>
</database>
• Will be validated by build process (DTD and
schema provided).
Hans Lellelid: Propel Your PHP Applications 13

build.properties
• Generator uses “properties” files (Phing)
• Propel needs to know (at least) your
RDBMS and project name.
• It's often simplest to start with the
provided “bookstore” example.
• Example minimal build.properties:
propel.project = myproj
propel.database = mysql
propel.database.url = mysql:dbname=test
Hans Lellelid: Propel Your PHP Applications 14

runtime-conf.xml
• Runtime config expressed in XML.
• Configures connection and (optionally)
PEAR logging facility.
• Gets converted to PHP by build process.
<config>
<propel>
<datasources default=\"myproj\">
<datasource id=\"myproj\">
<adapter>mysql</adapter>
<connection>
<dsn>mysql:dbname=test</dsn>
</connection>
</datasource>
</datasources>
</propel>
</config>
Hans Lellelid: Propel Your PHP Applications 15

Build!
• Run propel-gen /path/to/projdir to
build the SQL DDL and PHP classes.
• Watch output for errors. (They're red.)
Hans Lellelid: Propel Your PHP Applications 16

Initialize DB
• Use propel-gen /path/to/projdir
insert-sql to run the generated DDL
statements against your configured
database.
• This will delete any existing data!
Hans Lellelid: Propel Your PHP Applications 17

Start using new OM
• Initialize Propel
require_once 'propel/Propel.php';
Propel::init('/path/to/myproj-conf.php');
• Configure your include_path to include the
output directory.
– Propel 1.3 uses SPL autoload.
• Begin reading and writing DB rows with
your new object model.
Hans Lellelid: Propel Your PHP Applications 18

Cruising Altitude
Getting comfortable with Propel.
Hans Lellelid: Propel Your PHP Applications 19

Column Types
• Propel uses an abstract subset of SQL
types.
• SQL types are mapped to specific PHP
types.
• You can override the SQL type for a
column.
• Temporal values (DATE, TIME, TIMESTAMP)
will use PHP DateTime objects.
Hans Lellelid: Propel Your PHP Applications 20

Expressing Relationships
• Relationships between tables are defined
using foreign keys.
– Even for systems that don't support true FK
constraints.
• Propel supports single or composite foreign
keys.
• Support for deletion cascading emulation.
• The related objects can be get/set just like
simple column values.
Hans Lellelid: Propel Your PHP Applications 21

Selecting Rows
• retrieveByPK() static method exists to
select a single row.
• Criteria provides an OO approach to
building queries.
• Smart handling of column types.
• Multiple “Criterion” objects can be grouped
together to form complex queries.
• You can also use SQL, if you prefer.
Hans Lellelid: Propel Your PHP Applications 22

Customization
• Build properties customize code generation.
• Override method and constant naming from
the schema.xml
• Empty stub object & peer classes for
custom methods:
– New methods or
– Override parent (base) methods
Hans Lellelid: Propel Your PHP Applications 23

Over-Drive
Wait ... I thought we were using
airplane metaphors.
Hans Lellelid: Propel Your PHP Applications 24

Locator Objects (LOBs)
• LOB columns returned as PHP streams.
– This is the PDO design (though there are
some exceptions).
• Mutator methods support streams or
(string) file contents.
Hans Lellelid: Propel Your PHP Applications 25

Inheritance
• Propel supports table-per-class-hierarchy
inheritance.
• Subclasses can be enumerated in the
schema.xml (faster) or resolved at runtime
(more flexible).
• Plans in place for other inheritance models.
Hans Lellelid: Propel Your PHP Applications 26

Other Features
• Reverse engineer existing databases
(requires Creole)
• Import and export data as XML
• Generate Graphviz ERD from schema.xml
• Represent trees in SQL using nested set
approach.
Hans Lellelid: Propel Your PHP Applications 27

Extension Paths
• Integrating with other Phing projects
• Custom platform classes
– Affects generation of SQL DDL
• Custom builder classes
– Determine how your classes are built.
Hans Lellelid: Propel Your PHP Applications 28

The 2.0 Horizon
• Criteria redesign
• New inheritance models
• Eagerly awaiting PHP6 (or 5.3)
– Namespaces
– Late static binding
• Plugin-based builder framework.
Hans Lellelid: Propel Your PHP Applications 29

On Behalf of the Flight
Crew ...
Thanks for listening. :)
Hans Lellelid: Propel Your PHP Applications 30