= 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:Users/Documentation/1.3/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 [wiki:Users/Documentation/1.3/Schema Schema reference] document.

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

{{{
#!xml
<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:

{{{
#!xml
<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:

{{{
#!xml
<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
<?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:Users/Documentation/1.3/HowTos/CustomizingBuild for some ideas) -- but at a bare minimum, Propel needs to know:
 1. The name of your project,
 1. What RDBMS you are using, and
 1. 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, but required if you want to initialize db)
#
# This is the PDO DSN (see online docs http://www.php.net/pdo for more info)
propel.database.url = sqlite:/path/to/bookstore.db
# Other examples:
# propel.database.url = mysql:host=localhost;dbname=test
# propel.database.url = pgsql:host=localhost dbname=db-name user=db-username password=db-password
#
# If you are using MySQL or Oracle, you will have to specify any username and password separately
# propel.database.user = db-user
# propel.database.password = db-password
}}}

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
<?xml version="1.0" encoding="ISO-8859-1"?>

<config>
 <!-- Uncomment this if you have PEAR Log installed
 <log>
  <type>file</type>
  <name>/path/to/prople.log</name>
  <ident>propel-bookstore</ident>
  <level>7</level>
 </log>
 -->
 <propel>
  <datasources default="bookstore">
   <datasource id="bookstore"> <!-- this ID must match <database name=""> in schema.xml -->
    <adapter>sqlite</adapter> <!-- sqlite, mysql, myssql, oracle, or pgsql -->
    <connection>
     <dsn>sqlite2:/path/to/bookstore.db</dsn> <!-- the PDO connection DSN for database -->
    </connection>
   </datasource>
  </datasources>
 </propel>
</config>
}}}

See the [wiki:Users/Documentation/1.3/RuntimeConf runtime configuration reference] for a more detailed explanation of  this file.

Note that if you uncomment the <log> section, Propel will attempt to instantiate the Log class (from PEAR Log package) with the specified parameters and use that to log queries.  Propel's statement logging happens at the DEBUG level (7); errors and warnings are logged at the appropriate (non-debug) level.

== 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-conf" targets which, respectively,
 1. create the SQL DDL to create your database objects (tables, sequences, foreign keys, indexes, etc.),
 1. create the PHP5 classes that provide an OO representation of your database, and
 1. 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/bookstore-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 (using your database tools) and then use Propel to setup & initialize the database.

E.g. for MySQL:
{{{
$> mysqladmin create bookstore
}}}

The "insert-sql" target will apply the SQL statements from the {{{schema.sql}}} file to ''an existing'' 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 some databases have no way of checking to see whether a database object exists before attempting to DROP it (MySQL is a 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;
 1. a ''peer'' class, which is a static class that contains methods to operate on the table; and
 1. 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/BookTableMap.php`||Map class that contains 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.

Tip: Never add any code to the classes generated by Propel in the `om/` and `map/` directories; use the stub classes instead. This is because every time you call the `propel-gen` script, Propel generates all the `Base` files again and overrides any modification.

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, let's 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
<?php

// Set the include_path to include your generated OM 'classes' dir.
set_include_path("/path/to/bookstore/build/classes" . PATH_SEPARATOR . get_include_path());

require_once 'propel/Propel.php';

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

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

Continue reading the [wiki:Users/Documentation/1.4/BasicCRUD Basic CRUD Guide] to see how to perform the basic C.R.U.D. (Create, Retrieve, Update, Delete) operations using your Propel-generated classes.