はじめに

Doctrine Query Language (DQL)は複雑なオブジェクト読み取りを手助けするためのObject Query Languageです。リレーショナルデータを効率的に読み取るときに(例えばユーザーと電話番号を取得するとき)DQL(もしくは生のSQL)を使うことを常に考えるべきです。

この章ではDoctrine Query Languageの使い方の例をたくさん実演します。これらすべての例では[doc defining-models :name]の章で定義したスキーマを使うことを想定します。またテスト用に1つの追加モデルを定義します。

// models/Account.php

class Account extends Doctrine_Record { public function setTableDefinition() { $this->hasColumn('name', 'string', 255); $this->hasColumn('amount', 'decimal'); } }

YAMLフォーマットでの同じ例は次の通りです。[doc yaml-schema-files :name]の章でYAMLの詳細を読むことができます:

# schema.yml

Account: columns: name: string(255) amount: decimal

生のSQLを使う場合と比較すると、DQLは次の恩恵があります:

• 始めから結果セットの列ではなくレコード(オブジェクト)の読み取りのために設計されている
• DQLはリレーションを理解するのでSQLのjoinとjoinの条件を手動で入力する必要がない
• DQLは異なるデータベースでポータブルである
• DQLはレコード制限などとても複雑なアルゴリズムが組み込まれておりこれは開発者がオブジェクトを効率的に読み取るのを手助けする
• 条件付きの取得で一対多、多対多のリレーショナルデータを扱うときに時間を節約できる機能をサポートする

DQLの力が十分でなければ、オブジェクト投入に対して[doc native-sql RawSql API]を使うことを考えるべきです。

既に次の構文に慣れている方もいらっしゃるでしょうx:

CAUTION 次のコードは決して使わないでください。 これはオブジェクト投入用に多くのSQLクエリを使います。

// test.php

// ... $users = Doctrine_Core::getTable('User')->findAll();

foreach($users as $user) { echo $user->username . " has phonenumbers: ";

foreach($user->Phonenumbers as $phonenumber) {
    echo $phonenumber->phonenumber . "\n";
}

}

// ... $q = Doctrine_Query::create() ->from('User u') ->leftJoin('u.Phonenumbers p');

echo $q->getSqlQuery();

上記のクエリによって生成されるSQLを見てみましょう:

SELECT u.id AS uid, u.is\_active AS uis_active, u.is_super_admin

AS uis\_super\_admin, u.first\_name AS ufirst_name, u.last_name AS ulast\_name, u.username AS uusername, u.password AS upassword, u.type AS utype, u.created_at AS ucreated\_at, u.updated\_at AS uupdated_at, p.id AS pid, p.user\_id AS puser_id, p.phonenumber AS p__phonenumber FROM user u LEFT JOIN phonenumber p ON u.id = p.user_id

クエリを実行してデータで遊んでみましょう:

// test.php

// ... $users = $q->execute();

foreach($users as $user) { echo $user->username . " has phonenumbers: ";

foreach($user->Phonenumbers as $phonenumber) {
    echo $phonenumber->phonenumber . "\n";
}

}

CAUTION DQLの文字列で二重引用符(")を使うのは非推奨です。これはMySQLの標準では使えますがDQLにおいて識別子と混同される可能性があります。代わりに値に対してプリペアードステートメントを使うことが推奨されます。これによって適切にエスケープされます。

SELECTクエリ

SELECT文の構文:

SELECT [ALL | DISTINCT] , ... [FROM [WHERE ] [GROUP BY [ASC | DESC],

... ] [HAVING ] [ORDER BY [ASC | DESC], ...] [LIMIT OFFSET }]

SELECT文は1つもしくは複数のコンポーネントからデータを読み取るために使われます。 　 それぞれのselect_exprは読み取りたいカラムもしくは集約関数の値を示します。 すべてのSELECT文で少なくとも1つのselect_exprがなければなりません。

最初にサンプルのAccountレコードをinsertします:

// test.php

// ... $account = new Account(); $account->name = 'test 1'; $account->amount = '100.00'; $account->save();

$account = new Account(); $account->name = 'test 2'; $account->amount = '200.00'; $account->save();

test.phpを実行します:

$ php test.php

次のサンプルクエリでデータのselectをテストできます:

// test.php

// ... $q = Doctrine_Query::create() ->select('a.name') ->from('Account a');

echo $q->getSqlQuery();

上記のクエリによって生成されたSQLを見てみましょう:

SELECT a.id AS aid, a.name AS aname FROM account a

// test.php

// ... $accounts = q->execute(); print_r(accounts->toArray()); 上記の例では次の出力が生み出されます:

$ php test.php Array ( [0] => Array ( [id] => 1 [name] => test 1

[amount] => )

[1] => Array
    (
        [id] => 2
        [name] => test 2
        [amount] => 
    )

)

アスタリスクは任意のコンポーネントからすべてのカラムをselectするために使われます。アスタリスクを使うときでも実行されるSQLクエリは実際にはそれを使いません(Doctrineはアスタリスクを適切なカラムの名前に変換することで、データベースでのパフォーマンスの向上につながります)。

// test.php

// ... $q = Doctrine_Query::create() ->select('a.*') ->from('Account a');

echo $q->getSqlQuery();

最後のクエリの例から生成されたSQLとすぐ前に生成されたクエリで生成されたSQLを比較します:

SELECT a.id AS aid, a.name AS aname, a.amount AS a__amount FROM

account a

NOTE アスタリスクはAccountモデルに存在する実際のすべてのカラム名に置き換えられることに留意してください。

クエリを実行して結果を検査してみましょう:

// test.php

// ... $accounts = q->execute(); print_r(accounts->toArray()); 上記の例は次の出力を生み出します:

$ php test.php Array ( [0] => Array ( [id] => 1 [name] => test 1

[amount] => 100.00 )

[1] => Array
    (
        [id] => 2
        [name] => test 2
        [amount] => 200.00
    )

)

FROM句はレコードから読み取るコンポーネントを示します。

// test.php

// ... $q = Doctrine_Query::create() ->select('u.username, p.*') ->from('User u') ->leftJoin('u.Phonenumbers p')

echo $q->getSqlQuery();

getSql()への上記の呼び出しは次のSQLクエリを出力します:

SELECT u.id AS uid, u.username AS uusername, p.id AS p**id,

p.user_id AS p**user_id, p.phonenumber AS p__phonenumber FROM user u LEFT JOIN phonenumber p ON u.id = p.user_id

WHERE句は、選択されるためにレコードが満たさなければならない条件を示します。where_conditionは選択されるそれぞれの列に対してtrueに表示する式です。WHERE句が存在しない場合ステートメントはすべての列を選択します。

// test.php

// ... $q = Doctrine_Query::create() ->select('a.name') ->from('Account a') ->where('a.amount > 2000');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT a.id AS aid, a.name AS aname FROM account a WHERE a.amount >

2000

WHERE句において、集約(要約)関数を除いて、DQLがサポートする任意の関数と演算子を使うことができます。HAVING句は集約関数で結果を絞るために使うことができます:

// test.php

// ... $q = Doctrine_Query::create() ->select('u.username') ->from('User u') ->leftJoin('u.Phonenumbers p') ->having('COUNT(p.id) > 3');

echo $q->getSqlQuery();

getSql()を呼び出すと次のSQLクエリが出力されます:

SELECT u.id AS uid, u.username AS uusername FROM user u LEFT JOIN

phonenumber p ON u.id = p.user_id HAVING COUNT(p.id) > 3

ORDER BY句は結果のソートに使われます。

// test.php

// ... $q = Doctrine_Query::create() ->select('u.username') ->from('User u') ->orderBy('u.username');

echo $q->getSqlQuery();

上記のgetSql()を呼び出すと次のSQLクエリが出力されます:

SELECT u.id AS uid, u.username AS uusername FROM user u ORDER BY

u.username

LIMITとOFFSET句はレコードの数をrow_countに効率的に制限するために使われます。

// test.php

// ... $q = Doctrine_Query::create() ->select('u.username') ->from('User u') ->limit(20);

echo $q->getSqlQuery();

上記のgetSql()を呼び出すと次のSQLクエリが出力されます:

SELECT u.id AS uid, u.username AS uusername FROM user u LIMIT 20

UPDATEクエリ

UPDATE文の構文:

UPDATE SET = , = WHERE ORDER BY LIMIT

• UPDATE文はcomponent_nameの既存のレコードのカラムを新しい値で更新し影響を受けたレコードの数を返します。
• SET句は修正するカラムとそれらに渡される値を示します。
• オプションのWHERE句は更新するレコードを特定する条件を指定します。WHERE句がなければ、すべてのレコードが更新されます。
• オプションのORDER BY句はレコードが更新される順序を指定します。
• LIMIT句は更新できるレコードの数に制限をおきます。UPDATEの範囲を制限するために`LIMIT row\_count``を使うことができます。``LIMIT``句は列を変更する制限ではなく**列にマッチする制限**です。実際に変更されたのかに関わらず``WHERE``句を満たす``record_count`の列が見つかるとステートメントはすぐに停止します。

// test.php

// ... $q = Doctrine_Query::create() ->update('Account') ->set('amount', 'amount + 200') ->where('id > 200');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

UPDATE account SET amount = amount + 200 WHERE id > 200

更新の実行はシンプルです。次のクエリを実行するだけです:

// test.php

// ... $rows = $q->execute();

echo $rows;

DELETEクエリ

DELETE FROM WHERE ORDER BY LIMIT

• DELETE文はcomponent_nameからレコードを削除し削除されるレコードの数を返します。
• オプションのWHERE句は削除するレコードを特定する条件を指定します。WHERE句なしでは、すべてのレコードが削除されます。
• `ORDER BY`句が指定されると、指定された順序でレコードが削除されます。
• LIMIT句は削除される列の数に制限を置きます。record_countの数のレコードが削除されると同時にステートメントは停止します。

// test.php

// ... $q = Doctrine_Query::create() ->delete('Account a') ->where('a.id > 3');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

DELETE FROM account WHERE id > 3

DELETEクエリの実行は次の通りです:

// test.php

// ... $rows = $q->execute();

echo $rows;

NOTE DQLのUPDATEとDELETEクエリを実行すると影響を受けた列の数が返されます。

FROM句

構文:

FROM [[LEFT | INNER] JOIN ] ...

FROM句はレコードを読み取るコンポーネントを示します。複数のコンポーネントを名付けると、joinを実行することになります。指定されたそれぞれのテーブルに対して、オプションとしてエイリアスを指定できます。

次のDQLクエリを考えます:

// test.php

// ... $q = Doctrine_Query::create() ->select('u.id') ->from('User u');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT u.id AS u__id FROM user u

Userはクラス(コンポーネント)の名前でuはエイリアスです。常に短いエイリアスを使うべきです。大抵の場合これらによってクエリははるかに短くなるのと例えばキャッシュを利用するときに短いエイリアスが使われていればクエリのキャッシュされたフォームの取るスペースが少なくなるからです。

JOINの構文

DQL JOINの構文:

[[LEFT | INNER] JOIN ] [ON | WITH] [INDEXBY] , [[LEFT | INNER] JOIN

] [ON | WITH] [INDEXBY] , ... [[LEFT | INNER] JOIN ] [ON | WITH] [INDEXBY]

DQLはINNER JOINとLEFT JOINをサポートします。それぞれのjoinされたコンポーネントに対して、オプションとしてエイリアスを指定できます。

デフォルトのjoinの形式はLEFT JOINです。このjoinは`LEFT JOIN``句もしくはシンプルな'``,`'のどちらかを使うことで示せます。なので次のクエリは等しいです:

// test.php

// ... $q = Doctrine_Query::create() ->select('u.id, p.id') ->from('User u') ->leftJoin('u.Phonenumbers p');

$q = Doctrine_Query::create() ->select('u.id, p.id') ->from('User u, u.Phonenumbers p');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT u.id AS uid, p.id AS pid FROM user u LEFT JOIN phonenumber p

ON u.id = p.user_id

NOTE JOINの条件が自動的に追加されることに注意してください。DoctrineはUserとPhonenumberは関連していることを知っているのであなたに代わって追加できるからです。

`INNER JOIN``は共通集合を生み出します(すなわち、最初のコンポーネントのありとあらゆるレコードが2番目のコンポーネントのありとあらゆるレコードにjoinされます)。ですので例えば電話番号を1つかそれ以上持つすべてのユーザーを効率的に取得したい場合、基本的に``INNER JOIN`が使われます。

デフォルトではDQLは主キーのjoin条件を自動追加します:

// test.php

// ... $q = Doctrine_Query::create() ->select('u.id, p.id') ->from('User u') ->leftJoin('u.Phonenumbers p');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT u.id AS uid, p.id AS pid FROM User u LEFT JOIN Phonenumbers

p ON u.id = p.user_id

INDEXBYキーワード

INDEXBYキーワードはコレクション/配列のキーなどの特定のカラムをマッピングする方法を提供します。デフォルトではDoctrineは数値のインデックス付きの配列/コレクションに複数の要素のインデックスを作成します。マッピングはゼロから始まります。このビヘイビアをオーバーライドするには下記で示されるようにINDEXBYキーワードを使う必要があります:

// test.php

// ... $q = Doctrine_Query::create() ->from('User u INDEXBY u.username');

$users = $q->execute();

NOTE INDEXBYキーワードは生成されるSQLを変えません。コレクションのそれぞれのレコードのキーとして指定されたカラムでデータをハイドレイトするためにDoctrine_Queryによって内部で使われます。

これで$usersコレクションのユーザーは自身の名前を通してアクセスできます:

// test.php

// ... echo $user['jack daniels']->id;

INDEXBYキーワードは任意のJOINに適用できます。これは任意のコンポーネントがそれぞれ独自のインデックス作成のビヘイビアを持つことができることを意味します。次のコードにおいてUsersとGroupsの両方に対して異なるインデックス作成機能を使用しています。

// test.php

// ... $q = Doctrine_Query::create() ->from('User u INDEXBY u.username') ->innerJoin('u.Groups g INDEXBY g.name');

$users = $q->execute();

drinkers clubの作成日を出力してみましょう。

// test.php

// ... echo $users['jack daniels']->Groups['drinkers club']->createdAt;

WHERE句

構文:

WHERE

• WHERE句は、与えられた場合、選択されるためにレコードが満たさなければならない条件を示します。
• where_conditionは選択されるそれぞれの列に対してtrueに評価される式です。
• WHERE句が存在しない場合ステートメントはすべての列を選択します。
• 集約関数の値で結果を絞るときWHERE句の代わりにHAVING句が使われます。

Doctrine_Queryオブジェクトを使用する複雑なwhere条件を構築するためにaddWhere()、andWhere()、orWhere()、whereIn()、andWhereIn()、orWhereIn()、whereNotIn(), andWhereNotIn()、orWhereNotIn()メソッドを使うことができます。

すべてのアクティブな登録ユーザーもしくは管理者を読み取る例は次の通りです:

// test.php

// ... $q = Doctrine_Query::create() ->select('u.id') ->from('User u') ->where('u.type = ?', 'registered') ->andWhere('u.is_active = ?', 1) ->orWhere('u.is_super_admin = ?', 1);

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT u.id AS u__id FROM user u WHERE u.type = ? AND u.is_active =

? OR u.is_super_admin = ?

条件式

    $this->hasColumn('user_id', 'integer', null, array(
            'primary' => true
        )
    );
}

関数式

サブクエリ

GROUP BY、HAVING句

DQLのGROUP BY構文:

GROUP BY groupby_item {, groupby_item}*

DQL HAVINGの構文:

HAVING conditional_expression

`GROUP BY``と``HAVING`句は集約関数を扱うために使われます。次の集約関数がDQLで利用可能です: COUNT、MAX、MIN、AVG、SUM

アルファベット順で最初のユーザーを名前で選択する。

// test.php

// ... $q = Doctrine_Query::create() ->select('MIN(a.amount)') ->from('Account a');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT MIN(a.amount) AS a__0 FROM account a

すべてのアカウントの合計数を選択する。

// test.php

// ... $q = Doctrine_Query::create() ->select('SUM(a.amount)') ->from('Account a');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT SUM(a.amount) AS a__0 FROM account a

GROUP BY句を含まないステートメントで集約関数を使うと、すべての列でグルーピングすることになります。下記の例ではすべてのユーザーと彼らが持つ電話番号の合計数を取得します。

// test.php

// ... $q = Doctrine_Query::create() ->select('u.username') ->addSelect('COUNT(p.id) as num_phonenumbers') ->from('User u') ->leftJoin('u.Phonenumbers p') ->groupBy('u.id');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT u.id AS uid, u.username AS uusername, COUNT(p.id) AS p__0

FROM user u LEFT JOIN phonenumber p ON u.id = p.user_id GROUP BY u.id

HAVING句は集約値を使用する結果を狭めるために使われます。次の例では少なくとも2つの電話番号を持つすべてのユーザーを取得します。

// test.php

// ... $q = Doctrine_Query::create() ->select('u.username') ->addSelect('COUNT(p.id) as num_phonenumbers') ->from('User u') ->leftJoin('u.Phonenumbers p') ->groupBy('u.id') ->having('num_phonenumbers >= 2');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT u.id AS uid, u.username AS uusername, COUNT(p.id) AS p**0

FROM user u LEFT JOIN phonenumber p ON u.id = p.user_id GROUP BY u.id HAVING p**0 >= 2

次のコードで電話番号の数にアクセスできます:

// test.php

// ... $users = $q->execute();

foreach($users as $user) { echo $user->name . ' has ' . $user->num_phonenumbers . ' phonenumbers'; }

ORDER BY句

LIMITとOFFSET句

おそらく最も複雑機能であるDQLパーサーはLIMIT句パーサーです。DQL LIMIT句パーサーはLIMITデータベースポータビリティを考慮するだけでなく複雑なクエリ分析とサブクエリを使用することで列の代わりにレコードの数を制限できる機能を持ちます。

最初の20ユーザーと関連する電話番号を読み取ります:

// test.php

// ... $q = Doctrine_Query::create() ->select('u.username, p.phonenumber') ->from('User u') ->leftJoin('u.Phonenumbers p') ->limit(20);

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT u.id AS uid, u.username AS uusername, p.id AS p**id,

p.phonenumber AS p**phonenumber FROM user u LEFT JOIN phonenumber p ON u.id = p.user_id

名前付きクエリ

変化する可能性があるモデルを扱うが、クエリを簡単に更新できるようにする必要があるとき、クエリを定義する簡単な方法を見つける必要があります。例えば1つのフィールドを変更して何も壊れていないことを確認するためにアプリケーションのすべてのクエリを追跡する必要がある状況を想像してください。

名前付きクエリはこの状況を解決する素晴らしく効率的な方法です。これによってDoctrine_Queriesを作成しこれらを書き直すこと無く再利用できるようになります。

名前付きクエリのサポートはDoctrine\_Query\_Registryのサポートの上で構築されます。Doctrine\_Query_Registryはクエリを登録して名前をつけるためのクラスです。これはアプリケーションクエリの編成を手助けしこれに沿ってとても便利な機能を提供します。

レジストリオブジェクトのadd()メソッドを使用してこのクエリは追加されます。これは2つのパラメータ、クエリの名前と実際のDQLクエリを受け取ります。

// test.php

// ... $r = Doctrine_Manager::getInstance()->getQueryRegistry();

$r->add('User/all', 'FROM User u');

$userTable = Doctrine_Core::getTable('User');

// すべてのユーザーを見つける $users = $userTable->find('all');

このサポートを簡略化するために、Doctrine\_TableはDoctrine\_Query_Registryへのアクセサをサポートします。

    // Doctrine_Queryオブジェクトを使用して定義された名前付きのクエリ
    $this->addNamedQuery(
        'get.by.similar.usernames', Doctrine_Query::create()
            ->select('u.id, u.username')
            ->from('User u')
            ->where('LOWER(u.username) LIKE LOWER(?)')
    );
}

BNF

QL_statement ::= select_statement | update_statement |

delete_statement select_statement ::= select_clause from_clause [where_clause] [groupby_clause] [having_clause] [orderby_clause] update_statement ::= update_clause [where_clause] delete_statement ::= delete_clause [where_clause] from_clause ::= FROM identification_variable_declaration {, {identification_variable_declaration | collection_member_declaration``* identification_variable_declaration ::= range_variable_declaration { join | fetch_join }* range_variable_declaration ::= abstract_schema_name [AS ] identification_variable join ::= join_spec join_association_path_expression [AS ] identification_variable fetch_join ::= join_specFETCH join_association_path_expression association_path_expression ::= collection_valued_path_expression | single_valued_association_path_expression join_spec::= [LEFT [OUTER ] |INNER ]JOIN join_association_path_expression ::= join_collection_valued_path_expression | join_single_valued_association_path_expression join_collection_valued_path_expression::= identification_variable.collection_valued_association_field join_single_valued_association_path_expression::= identification_variable.single_valued_association_field collection_member_declaration ::= IN ( collection_valued_path_expression) [AS ] identification_variable single_valued_path_expression ::= state_field_path_expression | single_valued_association_path_expression state_field_path_expression ::= {identification_variable | single_valued_association_path_expression}.state_field single_valued_association_path_expression ::= identification_variable.{single_valued_association_field.}* single_valued_association_field collection_valued_path_expression ::= identification_variable.{single_valued_association_field.}collection\_valued\_association\_field state\_field ::= {embedded\_class\_state\_field.}simple_state_field update_clause ::=UPDATE abstract_schema_name [[AS ] identification_variable] SET update_item {, update_item}* update_item ::= [identification_variable.]{state_field | single_valued_association_field} = new_value new_value ::= simple_arithmetic_expression | string_primary | datetime_primary |

boolean_primary | enum_primary simple_entity_expression | NULL delete_clause ::=DELETE FROM abstract_schema_name [[AS ] identification_variable] select_clause ::=SELECT [DISTINCT ] select_expression {, select_expression}* select_expression ::= single_valued_path_expression | aggregate_expression | identification_variable | OBJECT( identification_variable) | constructor_expression constructor_expression ::= NEW constructor_name( constructor_item {, constructor_item}) constructor\_item ::= single\_valued\_path\_expression \| aggregate\_expression aggregate\_expression ::= {AVG \|MAX \|MIN \|SUM }( [DISTINCT ] state\_field\_path\_expression) \| COUNT ( [DISTINCT ] identification\_variable \| state\_field\_path\_expression \| single\_valued\_association\_path\_expression) where\_clause ::=WHERE conditional\_expression groupby\_clause ::=GROUP BY groupby\_item {, groupby\_item} groupby_item ::= single_valued_path_expression | identification_variable having_clause ::=HAVING conditional_expression orderby_clause ::=ORDER BY orderby_item {, orderby_item}* orderby_item ::= state_field_path_expression [ASC |DESC ] subquery ::= simple_select_clause subquery_from_clause [where_clause] [groupby_clause] [having_clause] subquery_from_clause ::= FROM subselect_identification_variable_declaration {, subselect_identification_variable_declaration}* subselect_identification_variable_declaration ::= identification_variable_declaration | association_path_expression [AS ] identification_variable | collection_member_declaration simple_select_clause ::=SELECT [DISTINCT ] simple_select_expression simple_select_expression::= single_valued_path_expression | aggregate_expression | identification_variable conditional_expression ::= conditional_term | conditional_expressionOR conditional_term conditional_term ::= conditional_factor | conditional_termAND conditional_factor conditional_factor ::= [NOT ] conditional_primary conditional_primary ::= simple_cond_expression |( conditional_expression) simple_cond_expression ::= comparison_expression | between_expression | like_expression | in_expression | null_comparison_expression | empty_collection_comparison_expression |

collection_member_expression | exists_expression between_expression ::= arithmetic_expression [NOT ]BETWEEN arithmetic_expressionAND arithmetic_expression | string_expression [NOT ]BETWEEN string_expressionAND string_expression | datetime_expression [NOT ]BETWEEN datetime_expressionAND datetime_expression in_expression ::= state_field_path_expression [NOT ]IN ( in_item {, in_item}* | subquery) in_item ::= literal | input_parameter like_expression ::= string_expression [NOT ]LIKE pattern_value [ESCAPE escape_character] null_comparison_expression ::= {single_valued_path_expression | input_parameter}IS [NOT ] NULL empty_collection_comparison_expression ::= collection_valued_path_expressionIS [NOT] EMPTY collection_member_expression ::= entity_expression [NOT ]MEMBER [OF ] collection_valued_path_expression exists_expression::= [NOT ]EXISTS (subquery) all_or_any_expression ::= {ALL |ANY |SOME } (subquery) comparison_expression ::= string_expression comparison_operator {string_expression | all_or_any_expression} | boolean_expression {= |<> } {boolean_expression | all_or_any_expression} | enum_expression {= |<> } {enum_expression | all_or_any_expression} | datetime_expression comparison_operator {datetime_expression | all_or_any_expression} | entity_expression {= |<> } {entity_expression | all_or_any_expression} | arithmetic_expression comparison_operator {arithmetic_expression | all_or_any_expression} comparison_operator ::== |> |>= |< |<= |<> arithmetic_expression ::= simple_arithmetic_expression | (subquery) simple_arithmetic_expression ::= arithmetic_term | simple_arithmetic_expression {+ |- } arithmetic_term arithmetic_term ::= arithmetic_factor | arithmetic_term {* |/ } arithmetic_factor arithmetic_factor ::= [{+ |- }] arithmetic_primary arithmetic_primary ::= state_field_path_expression | numeric_literal | (simple_arithmetic_expression) | input_parameter | functions_returning_numerics | aggregate_expression string_expression ::= string_primary | (subquery) string_primary ::= state_field_path_expression | string_literal | input_parameter | functions_returning_strings | aggregate_expression

datetime_expression ::= datetime_primary | (subquery) datetime_primary ::= state_field_path_expression | input_parameter | functions_returning_datetime | aggregate_expression boolean_expression ::= boolean_primary | (subquery) boolean_primary ::= state_field_path_expression | boolean_literal | input_parameter | enum_expression ::= enum_primary | (subquery) enum_primary ::= state_field_path_expression | enum_literal | input_parameter | entity_expression ::= single_valued_association_path_expression | simple_entity_expression simple_entity_expression ::= identification_variable | input_parameter functions_returning_numerics::= LENGTH( string_primary) | LOCATE( string_primary, string_primary[, simple_arithmetic_expression]) | ABS( simple_arithmetic_expression) | SQRT( simple_arithmetic_expression) | MOD( simple_arithmetic_expression, simple_arithmetic_expression) | SIZE( collection_valued_path_expression) functions_returning_datetime ::= CURRENT_DATE | CURRENT_TIME | CURRENT_TIMESTAMP functions_returning_strings ::= CONCAT( string_primary, string_primary) | SUBSTRING( string_primary, simple_arithmetic_expression, simple_arithmetic_expression)| TRIM( [[trim_specification] [trim_character]FROM ] string_primary) | LOWER( string_primary) | UPPER( string_primary) trim_specification ::=LEADING | TRAILING | BOTH

マジックファインダー

Doctrineはモデルに存在する任意のカラムでレコードを見つけることを可能にするDoctrineモデル用のマジックファインダー(magic finder)を提供します。ユーザーの名前でユーザーを見つけたり、グループの名前でグループを見つけるために役立ちます。通常これはDoctrine_Queryインスタンスを書き再利用できるようにこれをどこかに保存することが必要です。このようなシンプルな状況にはもはや必要ありません。

ファインダーメソッドの基本パターンは次の通りです: findBy%s(`value)もしくはfindOneBy%s(`\ value)です。%sはカラム名もしくはリレーションのエイリアスです。カラムの名前の場合探す値を提供しなければなりません。リレーションのエイリアスを指定する場合、見つけるリレーションクラスのインスタンスを渡すか、実際の主キーの値を渡すことができます。 最初に扱うUserTableインスタンスを読み取りましょう:

// test.php

// ... $userTable = Doctrine_Core::getTable('User');

find()メソッドを利用して主キーでUserレコードを簡単に見つけられます:

// test.php

// ... $user = $userTable->find(1);

ユーザー名で1人のユーザーを見つけたい場合は次のようにマジックファインダーを使うことができます:

// test.php

// ... $user = $userTable->findOneByUsername('jonwage');

レコード間のリレーションを利用してレコードでユーザーを見つけることができます。Userは複数のPhonenumbersを持つのでfindBy\*\*()メソッドにUserインスタンスを渡すことでこれらのPhonenumberを見つけることができます:

// test.php

// ... $phonenumberTable = Doctrine::getTable('Phonenumber');

$phonenumbers = phonenumberTable->findByUser(user); マジックファインダーはもう少し複雑な検索を可能にします。複数のプロパティによってレコードを検索するためにメソッド名でAndとOrキーワードを使うことができます。

$user = $userTable->findOneByUsernameAndPassword('jonwage',

md5('changeme'));

条件を混ぜることもできます。

$users = $userTable->findByIsAdminAndIsModeratorOrIsSuperAdmin(true,

true, true);

CAUTION これらは語句限られたマジックメソッドの用例で、つねに手書きのDQLクエリで展開することをおすすめします。これらのメソッドはリレーションシップなしの単独のレコードに素早くアクセスするための手段であり、素早くプロトタイプを書くのにもよいものです。

NOTE 上記のマジックファインダーはPHPの`[http://php.net/\_\_call **call()]``のオーバーロード機能を使うことで作成されます。内在する関数は``Doctrine\_Query``オブジェクトがビルドされる``Doctrine_Table::**call()`に転送され、実行されてユーザーに返されます。

クエリをデバッグする

Doctrine_Queryオブジェクトはクエリの問題をデバッグするための手助けになる機能を少々提供します:

ときにDoctrine_Queryオブジェクトに対して完全なSQL文字列を見たいことがあります:

// test.php

// ... $q = Doctrine_Query::create() ->select('u.id') ->from('User u') ->orderBy('u.username');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT u.id AS u__id FROM user u ORDER BY u.username

NOTE 上記のDoctrine\_Query::getSql()メソッドによって返されるSQLはトークンをパラメータに置き換えません。これはPDOのジョブでクエリを実行するとき置き換えが実行されるPDOにパラメータを渡します。Doctrine_Query::getParams()メソッドでパラメータの配列を読み取ることができます。

Doctrine_Queryインスタンス用のパラメータの配列を取得します:

// test.php

// ... print_r($q->getParams());

まとめ

Doctrine Query Languageはこれまでのところ最も高度で役に立つDoctrineの機能です。これによってRDBMSのリレーションからとても複雑なデータを簡単にかつ効率的に選択できます！

これでDoctrineの主要なコンポーネントの使い方を見たので[doc component-overview :name]の章に移りすべてを鳥の目で見ることにします。