Propelクイックスタートガイド
このガイドは簡単なデータベースとデータベースの中にあるデータを見つけたり操作するためのPHPクラスを作るステップを紹介することで、Propelがどの様に動いているかを理解してもらう為のものです。このガイドではシンプルにしたBookstore（本屋さん）プロジェクトの例を使います。（この例を複雑にしたものはgenerator/projects/ディレクトリ以下にあります。）
1. 作業ディレクトリを作ります
まず最初にbookstoreディレクトリをプロジェクト内に作ります。Propel generatorはデータベース定義ファイル(schema.xml)や(build.properties)などのビルド設定ファイルをこのディレクトリから読み出します。このディレクトリ内にSQLやPHP5クラスが生成されます。(にこれらのディレクトリの変更方法に関しては wiki:Ja/Users/Documentation/1.3/HowTos/CustomizingBuild を参照してください。)
2. データベースをXMLで記述
各テーブルに対応したクラス（とその関係）を作るにはデータベースをXMLで記述したものが必要になります。
XMLデータモデル定義のオーバービュー
Propel内でのデータモデル定義するためのXMLスキーマは実際のデータベース構造に対応しています。スキーマに関する完全なリファレンスはスキーマリファレンス?ページを参照してください。
XMLドキュメントの(root)タグには<database>タグが入ります。
<database name="bookstore" defaultIdMethod="native"> </database>
データベースの名前は"bookstore"。defaultIdMethodの属性はデータベースがネイティブで提供しているauto-increment/sequence機能を使ってauto-incrementにセットされた行を扱うということを示しています。
<database>タグの中に、データベース内のテーブルを定義します：
<database name="bookstore" defaultIdMethod="native"> <table name="book"> </table> <table name="author"> </table> </database>
そして各<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>
以上がPropelでXMLを使ってデータベースを記述する基本的な方法です。次のセクションで外部キーなど他の機能の紹介をします。
自分のschema.xmlを作る
これでbookstoreの全てのデータモデルをXMLで記述できるようになりました。まず最初にステップ１で作ったbookstoreディレクトリの中に新しいファイルschema.xmlを作ります。
以下がこれから使うスキーマの全てになります。(schema.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>
以上のXMLのほとんどは（前のセクションで）みたことがあるような感じがするか少なくとも直感的に分かるはずです。
3. ビルドの設定を行う
bookstoreプロジェクトをビルドするために、Propel generatorにもういくつかのことを教えてやる必要があります。この情報はbookstore内のbuild.propertiesファイルにあります。このファイルの中には他にもいろいろなことを設定することができます。( wiki:Users/Documentation/HowTos/CustomizingBuild? を参照してください。)少なくともPropelは以下のことを知っていることが必要です。
- プロジェクトの名前
- 使っているRDBMS
- データベースへの接続の方法
bookstoreディレクトリの中にbuild.propertiesファイルを作って、以下の内容をカット＆ペーストして、データベースへの設定を適当なものに変更してください。
# プロジェクトの名前 propel.project = bookstore # データベースのドライバー propel.database = sqlite # 接続用のパラメーター(必要であれば) propel.database.url = sqlite:/path/to/bookstore.db
これらのパラメーターはPropel generator用のもので、runtimeのものと共通である必要はありません。次にruntimeの設定を紹介します。
4. Runtimeの設定をする
runtimeの設定は生成されたオブジェクトモデルクラスや共通のPropel runtimeクラスを設定するのに使われます。この情報はSQLやPHPクラスをビルドするのには必要ありませんが、runtime設定はPHPに分かりやすいようにgeneratorがPHPの配列になった設定ファイルを生成するので、これらの属性をプロジェクトをビルドする前に設定することになります。
bookstoreディレクトリ内にruntime-conf.xmlという新しいファイルを作って、以下の設定をカット＆ペーストした後、(上の build.propertiesのファイルに指定されたように)bookstore.dbに適当なパスを入力してください。
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>
<dsn>sqlite2:/path/to/bookstore.db</dsn>
</connection>
</datasource>
</datasources>
</propel>
</config>
5. ビルド
Proprl 1.2からPEARを使うか圧縮パッケージやSubversionからインストールしたのに関わらずSQLとPHPのオブジェクトモデルをpropel-genスクリプトを使って生成できるようになりました。
bookstore}}プロジェクトディレクトリ内で{{{propel-genスクリプトを呼ぶことで、ビルドを実行することができます。propel-genはtargetパラメーターを指定することで、いろんな機能を動かすことができます。targetが指定されない場合は、デフォルトの"main" targetが実行されます。
"main"targetは以下の"sql", "om", "convert-props"を読み込みます
- (テーブル, シークエンス, 外部キー, インデックス, などの)データベースオブジェクトを作るためのSQL DDLを生成します
- オブジェクト指向でデータベースに対応したPHP5のクラスを生成します
- XML runtime設定をPHPでパースしやすいPHPの配列に変換します。
$> propel-gen /path/to/bookstore
bookstoreディレクトリの位置を指定する場合は絶対パスを使うように注意してください。
このコマンドのアウトプットから何が生成されて、どこに置かれたかが分かるようになります。
ビルドが成功して終わると、bookstore以下のような新しいディレクトリが作られそこにファイルが置かれます。
| パス | 説明 |
| bookstore/build/classes/bookstore/*.php | データベースアクセスのための生成されたPHPクラス |
| bookstore/build/sql/schema.sql | (テーブル、シークエンスなど)データベースオブジェクトを作るための、SQL DDLファイル |
| bookstore/build/conf/runtime-conf.php | runtime設定の入ったPHP配列 |
6. 生成されたSQLファイルとオブジェクトモデルファイルを使う
SQLファイルを使う
今さっき作ったSQL定義ファイルはbookstore/build/sql/schema.sqlにあります。このファイルはテーブルやその他のオブジェクトを作るためのSQLを含んでいます。既に存在しているデータベースからPropel用のPHPクラスファイルを生成するにはpropel-genに"create-db" targetをつけて呼ぶこともできますが、Propelにデータベースの初期化とセットアップを任せるのが一番簡単な方法です。
"insert-sql" target はschema.sqlファイル内のSQLの構文をデータベースに反映します。schema.sqlファイルはオブジェクト生成時に既に存在するオブジェクトをDROP(消して)してデータベースの内容を消してしまうのに注意してください。
$> propel-gen /path/to/bookstore insert-sql
使っているRDBMSによっては最初にスクリプトを走らせた際に"unable to DROP..."などとエラーが出てしまうこともあります。これはほとんどもデータベースがDROPを行う前にそのデータベースオブジェクトが存在するかどうかをチェックしていないからです(MySQLはこのチェックを行います）。これらのエラーは無視しても問題なく、２度目にこのスクリプトを流した時にこのエラーが表示されないことで確認することができます。
オブジェクトモデルを使う
全てのデータベース内のテーブルに対してPropelは3つのPHPクラスを用意します：
- objectクラス、これはデータベースの行に対応します。
- peerクラス、これはテーブルを操作する関数を含むスタティッククラスです。
- mapクラス、こちらにはruntime環境に必要なテーブルに対するメタデータが入っています。このクラスはまず使わないでしょう。
Propelはカスタム関数を追加することのできるobjectとpeerクラスに対して空のスタブクラスを用意します。ということはbookテーブルに対して以下のクラスが生成されるということです。
| クラス/場所* | 説明 |
| bookstore/om/BaseBook.php | bookテーブルの行に対応するベースクラス |
| bookstore/om/BaseBookPeer.php | bookテーブルを操作する為のベーススタティッククラス |
| bookstore/map/BookMapBuilder.php | "book"テーブルに対応するためのメタデータを含むMapクラス |
| bookstore/Book.php | BaseBookへのカスタム関数を入れるための空のサブクラス |
| bookstore/BookPeer.php | BaseBookPeerへのカスタム関数を入れるための空のサブクラス |
* これらのパスはbookstore/build/classes/への相対パスです。
前にもあるように、PHPクラスはbookstore/build/classes/bookstoreディレクトリに作られます。/path/to/bookstore/build/classesをディレクトリに追加するか、bookstore/build/classes/bookstoreの中身全部をinclude_pathにあるディレクトリ内に移動させる必要があります。
ここでは/path/to/bookstore/build/classes/bookstoreがinclude_path内に設定されているもとします。
Propelの初期化
Propelオブジェクトを使いはじめる前に、PHPスクリプト内でPropelを初期化する必要があります。このステップをPHPスクリプトの最初の方に読み込まれる、initかセットアップスクリプト内に含めることもできます。Propelを初期化することで、データベースアダプターやデータベース接続用のパラメーターが設定されます。またruntime設定ファイル内で<log>を設定した場合Loggingに関するパラメーターも設定されます。
php.iniを編集できない場合などはここでinclude_pathを設定することも可能です。
<?php // include_pathの設定 set_include_path("/path/to/bookstore/build/classes" . PATH_SEPARATOR . get_include_path()); Propel::init("/path/to/bookstore/build/conf/runtime-conf.php");
これでPropelクラスを使い始める準備ができました！
この先の基本的なCRUDを読んでPropelが生成したクラスを使って基本的なC.R.U.D (作成、所得、更新、削除）オペレーションの使い方を学びましょう。
