Propel Quickstart Guide

This guide aims to bring you up to speed with how Propel works by walking through the creation of a simple database and PHP classes needed to find & manipulate data in the database. This guide uses a simplified version of the Bookstore example project (a more extensive example of this project is available in the generator/projects/ directory).

1. Create a Working Directory

Start by creating a bookstore directory for your project. The Propel generator expects to find your database definition file (schema.xml) and your build configuration options (build.properties) in this directory. This directory is also where your build SQL and PHP5 classes will be stored. (See wiki:Documentation/1.2/HowTos/CustomizingBuild for information about how you can customize the build.)

2. Describing Your Database in XML

In order to create classes that accurately represent your tables (and the relationships between them) you need to create an XML representation of your database.

Overview of XML Datamodel Definition

The XML schema for defining your datamodel in Propel closely follows the actual structure of the database. For a full reference of the schema, see the Schema reference document.

The top-most (root) tag of the the XMl document is the <database> tag.

<database name="bookstore" defaultIdMethod="native">

</database>

The database name will be "bookstore". The defaultIdMethod attribute indicates that you want to use the database's "native" auto-increment/sequence features to handle id columns that are set to auto-increment.

Within the <database> tags, you can define one or more tables that will be present in your database:

<database name="bookstore" defaultIdMethod="native">
  <table name="book">
  </table>
  <table name="author">
  </table>
</database>

And within each set of <table> tags, you define the columns that belong in that table:

<database name="bookstore" defaultIdMethod="native">
  <table name="book">
    <column name="id" type="integer" required="true" primaryKey="true" autoIncrement="true"/>
    <column name="title" type="varchar" size="255" required="true" />
  </table>
  <table name="author">
    <column name="id" type="integer" required="true" primaryKey="true" autoIncrement="true"/>
    <column name="first_name" type="varchar" size="128" required="true"/>
    <column name="last_name" type="varchar" size="128" required="true"/>
  </table>
</database>

That's the basic process of describing your database in XML for Propel. We'll look at other features like foreign-keys in the next section.

Creating your schema.xml

Ok, now you're ready to define the complete bookstore datamodel in XML. Start by creating a new file, schema.xml, in the bookstore directory that you created in step 1.

Here is the full schema that we will use. (Paste this into your schema.xml file and save it.)

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>

<database name="bookstore" defaultIdMethod="native">

 <table name="book" description="Book Table">
  <column name="book_id" type="integer" primaryKey="true" autoIncrement="true" required="true" description="Book Id"/>
  <column name="title" type="varchar" size="255" required="true" description="Book Title"/>
  <column name="isbn" type="varchar" size="24" required="true" phpName="ISBN" description="ISBN Number"/>
  <column name="publisher_id" type="integer" required="true" description="Foreign Key for Publisher"/>
  <column name="author_id" type="integer" required="true" description="Foreign Key for Author"/>
  <foreign-key foreignTable="publisher">
   <reference local="publisher_id" foreign="publisher_id"/>
  </foreign-key>
  <foreign-key foreignTable="author">
   <reference local="author_id" foreign="author_id"/>
  </foreign-key>
 </table>

 <table name="publisher" description="Publisher Table">
  <column name="publisher_id" type="integer" required="true" primaryKey="true" autoIncrement="true" description="Publisher Id"/>
  <column name="name" type="varchar" size="128" required="true" description="Publisher Name"/>
 </table>

 <table name="author" description="Author Table">
  <column name="author_id" type="integer" required="true" primaryKey="true" autoIncrement="true" description="Author Id"/>
  <column name="first_name" type="varchar" size="128" required="true" description="First Name"/>
  <column name="last_name" type="varchar" size="128" required="true" description="Last Name"/>
 </table>

</database>

Most of the XML above probably looks familiar (from previous section) or at least (hopefully) fairly intuitive.

3. Setting Build Configuration

In order to build your bookstore project, the Propel generator needs to know a few additional pieces of information. It expects to find this information in a build.properties file in your bookstore directory. There is a great deal of information that can be specified here (see wiki:Documentation/HowTos/CustomizingBuild? for some ideas) -- but at a bare minimum, Propel needs to know:

1. The name of your project,
2. What RDBMS you are using, and
3. How to connect to your database (assuming you want Propel to create the tables for you)

Create a build.properties file in your bookstore directory and paste in the properties below, substituting an appropriate path for your database:

# The name of the project 
propel.project = bookstore
 
# The database driver 
propel.database = sqlite

# The connection parameters (optional)
propel.database.url = sqlite:///path/to/bookstore.db
#              note 3 slashes ^   (sqlite:// + /path/to/bookstore.db)

Note that these properties are for the Propel generator and don't (necessarily) have anything in common with the runtime configuration, which we will look at next.

4. Setting Runtime Configuration

The runtime configuration is used in your application to configure your generated object model classes and the shared Propel runtime classes. This information is not needed for building your SQL and PHP classes, but the runtime configuration is transformed into a more PHP "friendly" array format by the generator, so it makes sense to set these properties before building the project.

Create a new file called runtime-conf.xml inside your bookstore directory and paste in the following configuration, substituting in the correct path to your bookstore.db file (as specified above in build.properties file).

<?xml version="1.0" encoding="ISO-8859-1"?>

<config>
 <log>
  <ident>propel-bookstore</ident>
  <level>7</level>
 </log>
 <propel>
  <datasources default="bookstore">
   <datasource id="bookstore">
    <!-- the Propel adapter will usually be the same as phptype of connection DSN -->
    <adapter>sqlite</adapter>
    <connection>
     <phptype>sqlite</phptype>
     <database>/path/to/bookstore.db</database>
     <hostspec></hostspec>
     <username></username>
     <password></password>
    </connection>
   </datasource>
  </datasources>
 </propel>
</config>

5. Building

As of Propel 1.2, you can use the propel-gen script to generate the SQL and PHP object model for your project, whether you installed Propel using PEAR or conventional packages / SVN.

You can execute the build by calling the propel-gen script with the path to your bookstore}} project directory. The {{{propel-gen script can perform many different functions, which can be selected by specifying a second target parameter. When no target is specified, the default "main" target is executed.

The "main" target invokes the "sql", "om", and "convert-props" targets which, respectively,

1. create the SQL DDL to create your database objects (tables, sequences, foreign keys, indexes, etc.),
2. create the PHP5 classes that provide an OO representation of your database, and
3. convert the XML runtime configuration into a PHP array that is easier (quicker) for PHP to parse.

$> propel-gen /path/to/bookstore

Note that you must use an absolute path when specifying the location of the bookstore directory.

You should see output from this command that lets you know in more detail what is being created and where it is being placed.

Assuming that the build finished successfully, you should have the following new directories (containing files) bookstore directory.

Path	Description
bookstore/build/classes/bookstore/*.php	The generated PHP classes that will be used to access your database.
bookstore/build/sql/schema.sql	The SQL DDL file that creates the database objects (tables, sequences, etc.)
bookstore/build/conf/runtime-conf.php	The converted PHP array that holds your runtime configuration.

6. Using the Generated SQL and OM Files

Using the SQL Files

The SQL definition file that we just created can be found at bookstore/build/sql/schema.sql. This file contains the SQL to create tables (and other objects) in an already-created database. For certain databases you can call propel-gen with the "create-db" target; however, it is usually easier to create the database (and set up the access permissions, etc.) outside of Propel and then use Propel to setup & initialize the database.

The "insert-sql" target will apply the SQL statements from the schema.sql file to the database. Note that the schema.sql file will DROP any existing objects before creating them, which will effectively erase your database.

$> propel-gen /path/to/bookstore insert-sql

Depending on which RDBMS you are using, it may be normal to see some errors (e.g. "unable to DROP...") when you first run this script. This is because many databases have no way of checking to see whether a database object exists before attempting to DROP it (MySQL is the notable exception). It is safe to disregard these errors (and you can always run the script a second time to make sure that the errors are no longer present).

Using the Object Model

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

1. an object class, which represents a row in the database;
2. a peer class, which is a static class that contains methods to operate on the table; and
3. a map class, which contains metadata information about the table that is needed for the runtime environment (you likely won't need to ever use this class).

Propel also creates empty stub classes for the object and peer classes which is where you can put customized functionality. So, this means that for the "book" table, the following classes will be created:

Class/Location*	Description
bookstore/om/BaseBook.php	Base class for representing a row from the "book" table.
bookstore/om/BaseBookPeer.php	Base static class for performing operations on "book" table.
bookstore/map/BookMapBuilder.php	Map class that creates a metadata represention of "book" table
bookstore/Book.php	Empty subclass for custom methods & overriding methods from BaseBook
bookstore/BookPeer.php	Empty peer subclass for custom methods & overriding methods from BaseBookPeer

• These paths are relative to bookstore/build/classes/ directory.

As we saw earlier, PHP classes have been created in the bookstore/build/classes/bookstore directory. You can either add the /path/to/bookstore/build/classes directory to your include_path or move the entire bookstore/build/classes/bookstore directory to a location that is already on on your include_path.

For demonstration purposes, I will assume that you've added /path/to/bookstore/build/classes/bookstore to your include_path.

Initializing Propel

Before you can begin using your Propel objects, you must initialize Propel in your PHP script. You may wish to do this step in an init or setup script that included at the beginning of your PHP scripts. Initializing Propel configures the database adapter & database connection parameters and sets up any logging (if you specified a <log> section in the rutnime config file).

You may also want to set your include_path in this initialization script -- if you aren't setting it in php.ini (or any of the other places INI options can be specified).

<?php

// Set the include
set_include_path("/path/to/bookstore/build/classes" . PATH_SEPARATOR . get_include_path());

Propel::init("/path/to/bookstore/build/conf/runtime-conf.php");

Now you are ready to include and begin using your Propel classes!

Continue reading the Basic CRUD Guide to see how to perform the basic C.R.U.D. (Create, Retrieve, Update, Delete) operations using your Propel-generated classes.