/propel_14/vendor/propel/docs/guide/02-QuickStart.txt

  1= Propel Quickstart Guide =
  2
  3This 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).
  4
  5== 1. Create a Working Directory ==
  6
  7Start 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.) 
  8
  9== 2. Describing Your Database in XML ==
 10
 11In order to create classes that accurately represent your tables (and the relationships between them) you need to create an XML representation of your database.
 12
 13=== Overview of XML Datamodel Definition ===
 14
 15The 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.
 16
 17The top-most (root) tag of the the XMl document is the ''<database>'' tag.
 18
 19{{{
 20#!xml
 21<database name="bookstore" defaultIdMethod="native">
 22
 23</database>
 24}}}
 25
 26The 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.
 27
 28Within the ''<database>'' tags, you can define one or more tables that will be present in your database:
 29
 30{{{
 31#!xml
 32<database name="bookstore" defaultIdMethod="native">
 33  <table name="book">
 34  </table>
 35  <table name="author">
 36  </table>
 37</database>
 38}}}
 39
 40And within each set of ''<table>'' tags, you define the columns that belong in that table:
 41
 42{{{
 43#!xml
 44<database name="bookstore" defaultIdMethod="native">
 45  <table name="book">
 46    <column name="id" type="integer" required="true" primaryKey="true" autoIncrement="true"/>
 47    <column name="title" type="varchar" size="255" required="true" />
 48  </table>
 49  <table name="author">
 50    <column name="id" type="integer" required="true" primaryKey="true" autoIncrement="true"/>
 51    <column name="first_name" type="varchar" size="128" required="true"/>
 52    <column name="last_name" type="varchar" size="128" required="true"/>
 53  </table>
 54</database>
 55}}}
 56
 57That'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.
 58
 59=== Creating your schema.xml ===
 60
 61Ok, 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.
 62
 63Here is the full schema that we will use.  (Paste this into your {{{schema.xml}}} file and save it.)
 64
 65{{{
 66#!xml
 67<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
 68
 69<database name="bookstore" defaultIdMethod="native">
 70
 71 <table name="book" description="Book Table">
 72  <column name="book_id" type="integer" primaryKey="true" autoIncrement="true" required="true" description="Book Id"/>
 73  <column name="title" type="varchar" size="255" required="true" description="Book Title"/>
 74  <column name="isbn" type="varchar" size="24" required="true" phpName="ISBN" description="ISBN Number"/>
 75  <column name="publisher_id" type="integer" required="true" description="Foreign Key for Publisher"/>
 76  <column name="author_id" type="integer" required="true" description="Foreign Key for Author"/>
 77  <foreign-key foreignTable="publisher">
 78   <reference local="publisher_id" foreign="publisher_id"/>
 79  </foreign-key>
 80  <foreign-key foreignTable="author">
 81   <reference local="author_id" foreign="author_id"/>
 82  </foreign-key>
 83 </table>
 84
 85 <table name="publisher" description="Publisher Table">
 86  <column name="publisher_id" type="integer" required="true" primaryKey="true" autoIncrement="true" description="Publisher Id"/>
 87  <column name="name" type="varchar" size="128" required="true" description="Publisher Name"/>
 88 </table>
 89
 90 <table name="author" description="Author Table">
 91  <column name="author_id" type="integer" required="true" primaryKey="true" autoIncrement="true" description="Author Id"/>
 92  <column name="first_name" type="varchar" size="128" required="true" description="First Name"/>
 93  <column name="last_name" type="varchar" size="128" required="true" description="Last Name"/>
 94 </table>
 95
 96</database>
 97}}}
 98
 99Most of the XML above probably looks familiar (from previous section) or at least (hopefully) fairly intuitive.
100
101
102== 3. Setting Build Configuration ==
103
104In 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:
105 1. The name of your project,
106 1. What RDBMS you are using, and
107 1. How to connect to your database (assuming you want Propel to create the tables for you)
108
109
110Create a {{{build.properties}}} file in your {{{bookstore}}} directory and paste in the properties below, substituting an appropriate path for your database:
111
112{{{
113# The name of the project 
114propel.project = bookstore
115 
116# The database driver 
117propel.database = sqlite
118
119# The connection parameters (optional, but required if you want to initialize db)
120#
121# This is the PDO DSN (see online docs http://www.php.net/pdo for more info)
122propel.database.url = sqlite:/path/to/bookstore.db
123# Other examples:
124# propel.database.url = mysql:host=localhost;dbname=test
125# propel.database.url = pgsql:host=localhost dbname=db-name user=db-username password=db-password
126#
127# If you are using MySQL or Oracle, you will have to specify any username and password separately
128# propel.database.user = db-user
129# propel.database.password = db-password
130}}}
131
132Note 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.
133
134
135== 4. Setting Runtime Configuration ==
136
137The ''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.
138
139Create 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).
140
141{{{
142#!xml
143<?xml version="1.0" encoding="ISO-8859-1"?>
144
145<config>
146 <!-- Uncomment this if you have PEAR Log installed
147 <log>
148  <type>file</type>
149  <name>/path/to/prople.log</name>
150  <ident>propel-bookstore</ident>
151  <level>7</level>
152 </log>
153 -->
154 <propel>
155  <datasources default="bookstore">
156   <datasource id="bookstore"> <!-- this ID must match <database name=""> in schema.xml -->
157    <adapter>sqlite</adapter> <!-- sqlite, mysql, myssql, oracle, or pgsql -->
158    <connection>
159     <dsn>sqlite2:/path/to/bookstore.db</dsn> <!-- the PDO connection DSN for database -->
160    </connection>
161   </datasource>
162  </datasources>
163 </propel>
164</config>
165}}}
166
167See the [wiki:Users/Documentation/1.3/RuntimeConf runtime configuration reference] for a more detailed explanation of  this file.
168
169Note 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.
170
171== 5. Building ==
172
173As 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.
174
175You 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.
176
177The "main" target invokes the "sql", "om", and "convert-conf" targets which, respectively,
178 1. create the SQL DDL to create your database objects (tables, sequences, foreign keys, indexes, etc.),
179 1. create the PHP5 classes that provide an OO representation of your database, and
180 1. convert the XML runtime configuration into a PHP array that is easier (quicker) for PHP to parse.
181
182{{{
183$> propel-gen /path/to/bookstore
184}}}
185
186''Note that you must use an absolute path when specifying the location of the {{{bookstore}}} directory.''
187
188You should see output from this command that lets you know in more detail what is being created and where it is being placed.
189
190Assuming that the build finished successfully, you should have the following new directories (containing files) {{{bookstore}}} directory.
191
192||'''Path'''||'''Description'''||
193||bookstore/build/classes/bookstore/*.php||The generated PHP classes that will be used to access your database.||
194||bookstore/build/sql/schema.sql||The SQL DDL file that creates the database objects (tables, sequences, etc.)||
195||bookstore/build/conf/bookstore-conf.php||The converted PHP array that holds your runtime configuration.||
196
197== 6. Using the Generated SQL and OM Files ==
198
199=== Using the SQL Files ===
200
201The 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.
202
203E.g. for MySQL:
204{{{
205$> mysqladmin create bookstore
206}}}
207
208The "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.'''
209
210{{{
211$> propel-gen /path/to/bookstore insert-sql
212}}}
213
214Depending 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).
215
216=== Using the Object Model ===
217
218For every table in the database, Propel creates 3 PHP classes:
219 1. an ''object'' class, which represents a row in the database;
220 1. a ''peer'' class, which is a static class that contains methods to operate on the table; and
221 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).
222
223Propel 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:
224
225||'''Class/Location*'''||'''Description'''||
226||`bookstore/om/BaseBook.php`||Base class for representing a row from the "book" table.||
227||`bookstore/om/BaseBookPeer.php`||Base static class for performing operations on "book" table.||
228||`bookstore/map/BookTableMap.php`||Map class that contains a metadata represention of "book" table||
229||`bookstore/Book.php`||Empty subclass for custom methods & overriding methods from `BaseBook`||
230||`bookstore/BookPeer.php`||Empty peer subclass for custom methods & overriding methods from `BaseBookPeer`||
231
232* ''These paths are relative to `bookstore/build/classes/` directory.
233
234Tip: 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.
235
236As 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''.
237
238For demonstration purposes, let's assume that you've added `/path/to/bookstore/build/classes/bookstore` to your ''include_path''.
239
240==== Initializing Propel ====
241
242Before 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).
243
244You 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).
245
246{{{
247#!php
248<?php
249
250// Set the include_path to include your generated OM 'classes' dir.
251set_include_path("/path/to/bookstore/build/classes" . PATH_SEPARATOR . get_include_path());
252
253require_once 'propel/Propel.php';
254
255Propel::init("/path/to/bookstore/build/conf/bookstore-conf.php");
256}}}
257
258Now you are ready to include and begin using your Propel classes!
259
260Continue 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.