/propel_14/vendor/propel/docs/guide/02-QuickStart.txt
Plain Text | 260 lines | 184 code | 76 blank | 0 comment | 0 complexity | 4d5b6eacdc0d30c0e8fb808a1fe76b41 MD5 | raw file
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.