Propelクィックスタートガイド
このガイドの目的はデータを見つけ操作をするために必要なシンプルなデータベースの作成とPHPクラスの作成を通して、Propelの使う作業を速くすることが目的です。このガイドはBookstore exampleオブジェクトの簡略化されたバージョンを使用します。(このプロジェクトのより発展的な例はgenerator/projects/ディレクトリで利用可能です)
1. ワーキングディレクトリを作成する
bookstoreディレクトリを作成することでプロジェクトを始めます。Propelジェネレータはデータベース定義ファイル(schema.xml)を見つけることとこのディレクトリでビルドコンフィギュレーションオプション(build.properties)を見つけることを期待します。このディレクトリはSQLとPHP5クラスが保存される場所でもあります。(wiki:Users/Documentation/1.2/HowTos/CustomizingBuild にどのようにビルドをカスタマイズすることができるのかについての情報があります。)
2. XMLでデータベースを記述する
テーブル(とそれらの関係)を正確に表現するクラスを作成するために、データベースのXML表現を作成する必要があります。
XMLデータモデルの概要
Propelでデータモデルを定義するためのXMLスキーマは厳密にデータベースの実際の構造に従います。スキーマの全リファレンスに関しては、Schema referenceドキュメントをご覧下さい。
XMLドキュメントの一番上の(ルート)タグは<database>タグです。
<database name="bookstore" defaultIdMethod="native"> </database>
データベース名は"bookstore"にします。オートインクリメントに設定されたidカラムを取り扱うためにdefaultIdMethod属性はあなたがデータベースの"native"なオートインクリメント/シーケンス機能を使いたいことを示します。
<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を作成する
OK、これで完全なbookstoreデータモデルをXMLで定義する準備が整いました。新しいファイルschema.xml、をステップ1で作成したbookstoreディレクトリに作成をして始めて下さい。
これが使う全スキーマです。(これを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" 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" 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ジェネレータは追加情報が必要です。bookstoreディレクトリでbuild.propertiesファイルでこの情報が見つかることが要求されます。ここで指定できる情報はたくさんあります(いくつかのアイディアに関してはwiki:Users/Documentation/HowTos/CustomizingBuild?をご覧下さい) -- しかし最小限では、Propelは次の情報を知る必要があります:
- プロジェクトの名前、
- 何のRDBMSを使用しているか、と
- どのようにデータベースに接続をするのか (Propelがテーブルを作ってくれることを前提とします)
bookstoreディレクトリにbuild.propertiesファイルを作成し、下記のプロパティにペーストし、データベースのための適切なパスを置き換えて下さい:
# プロジェクトの名前 propel.project = bookstore # データベースドライバ propel.database = sqlite # 接続パラメータ (オプション) propel.database.url = sqlite:///path/to/bookstore.db # 3つのスラッシュに注意↑ (sqlite:// + /path/to/bookstore.db)
これらのプロパティはPropelジェネレータのためにあり、次に見るランタイムコンフィギュレーションでは(必ずしも)共通ではありません。
4. ランタイムコンフィギュレーションを設定する
ランタイムコンフィギュレーションはアプリケーションで生成されたオブジェクトモデルクラスと共有Propelランタイムクラスを設定するために使用されます。この情報はSQLとPHPクラスをビルドするために必要ではありませんが、ランタイムコンフィギュレーションはジェネレータによってよりPHPに"フレンドリー"な配列の形式に変換されるので、プロジェクトをビルドする前にこれらのプロパティを設定することは道理にかなっています。
bookstoreディレクトリの内部にruntime-conf.xmlと呼ばれる新しいファイルを作成し、次のコンフィギュレーションをペーストします。bookstore.dbファイルへの適切なパスに置き換えて下さい(上記のbuild.propertiesファイルで指定されたものです)。
<?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. ビルド
Propel 1.2に関しては、PEAR、伝統的なパッケージ/ SVNにインストールしたにかかわらず、あなたのプロジェクトに関するSQLとPHPオブジェクトモデルを生成するためにpropel-genスクリプトを使用することが出来ます。
bookstoreプロジェクトディレクトリへのパスと一緒にpropel-genスクリプトを呼び出すことでビルドを実行することが出来ます。propel-genスクリプトは多くの異なる2番目のターゲットパラメータを指定することで選択できる機能を実行出来ます。ターゲットが指定されない場合、デフォルトの"main"ターゲットが実行されます。
"main"ターゲットは、"sql"、"om"、"convert-props"ターゲットを発動します。それぞれの内容は次の通りです。
- データベースオブジェクト(テーブル、シーケンス、外部キー、インデックスなど)を作成するためにSQL DDLを作成します、
- データベースのオブジェクト指向表現を提供するPHP5のクラスを作成し、そして
- XMLランタイムコンフィギュレーションを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 | ランタイムコンフィギュレーションを保持する変換されたPHP配列。 |
6. 生成されたSQLファイルとOMファイルを使用する
SQLファイルを使用する
先ほど作成したSQL定義ファイルはbookstore/build/sql/schema.sqlで見つかります。このファイルは既に作成されたデータベースでテーブル(と他のオブジェクト)を作成するSQLを含みます。特定のデータベースのために、"create-db"ターゲットでpropel-genを呼び出すことが出来ます; しかしながら、通常はPropelの外部でデータベースを作成する(こととアクセス権限をセットアップするなどの)方が簡単でデータベースをセットアップと初期化するためにPorpelを使用します。
"insert-sql"ターゲットはschema.sqlファイルからのSQL命令文をデータベースに適用します。schema.sqlはオブジェクトを作成する前に既存のオブジェクトをDROPすることに留意して下さい。効果的にデータベースを削除します。
$> propel-gen /path/to/bookstore insert-sql
使用しているRDBMSによっては、最初にこのスクリプトを実行したとき、エラー(例えば"unable to DROP...")をみることは通常であるかもしれません。これは多くのデータベースはデータベースオブジェクトをDROPをしようとする前にそれらが存在するかどうか確認する方法を持たないからです(MySQLは有名な例外です)。これらのエラーを無視することは安全です(そしてエラーがもはや存在しないことを確認するためにスクリプトを2回目に実行することは常に可能です)。
オブジェクトモデルを使用する
データベースのすべてのテーブルで、Propelは3つのPHPクラスを作成します:
- objectクラスはデータベースの列を表します;
- peerクラスはテーブル上で実行するメソッドを含む静的なクラスです; そして
- mapクラス、ランタイム環境に必要なテーブルに関するメタデータ情報を含みます(あなたがこのクラスを使う必要はおそらくないでしょう)。
Propelはカスタマイズした機能性を設置することが出来るobjectとpeerクラスのために空のスタブクラスも作成します。このことは"book"テーブルのために、次のクラスが作成されることを意味します:
| クラス/位置* | 説明 |
| bookstore/om/BaseBook.php | "book"テーブルから列を表現するための基本クラス。 |
| bookstore/om/BaseBookPeer.php | "book"テーブル上でオペレーションを実行するための基本的な静的クラス。 |
| bookstore/map/BookMapBuilder.php | "book"テーブルのメタデータ表現を作成するマップクラス |
| bookstore/Book.php | BaseBookからのカスタムクラスとオーバーライディングメソッドのための空のサブクラス |
| bookstore/BookPeer.php | BaseBookPeerからのカスタムクラスとオーバーライディングメソッドのための空のpeerサブクラス |
* これらのパスはbookstore/build/classes/ディレクトリに対して相対的です。
前で見たように、PHPクラスはbookstore/build/classes/bookstoreディレクトリに作成されました。/path/to/bookstore/build/classesディレクトリをinclude_pathに追加するもしくはbookstore/build/classes/bookstore全体をinclude_path上にある場所に移動します。
デモンストレーションの目的のために、あなたが/path/to/bookstore/build/classes/bookstoreをinclude_pathに追加したことを前提とします。
Propelを初期化する
Propelオブジェクトを使用する前に、PHPクラスでPropelを初期化しなければなりません。 PHPスクリプトの始めに含まれているinitもしくはsetupスクリプトでこのステップを行うことが出来ます。Propelの初期化によってデータベースアダプタとデータベース接続パラメータが設定されロギングがセットアップされます(ランタイムコンフィグファイルで<log>セクションを指定した場合です)。
この初期化スクリプトでinclude_pathを設定したいとします-- php.iniで設定されていない場合です(もしくはINIオプションを設置した他のものを指定することが出来ます)。
<?php // includeを設定する set_include_path("/path/to/bookstore/build/classes" . PATH_SEPARATOR . get_include_path()); Propel::init("/path/to/bookstore/build/conf/runtime-conf.php");
これでPropelクラスを使用してインクルードと始める準備が出来ました！
Propelで生成されたクラスを使用してどのように基本的なC.R.U.D. (Create, Retrieve, Update, Delete)オペレーションを実行するのかBasic CRUD Guideを読み続けて下さい。
