Behaviours

紹介

Doctrineにはモデルにそのまま使える機能を提供するテンプレートが搭載されています。モデルでこれらのテンプレートを簡単に有効にできます。Doctrine_Recordsで直接行うもしくはYAMLでモデルを管理しているのであればこれらをYAMLスキーマで指定できます。

次の例ではDoctrineに搭載されているビヘイビアの一部を実演します。

Versionable

バージョン管理の機能を持たせるためにBlogPostモデルを作成しましょう:

// models/BlogPost.php

class BlogPost extends Doctrine_Record { public function setTableDefinition() { $this->hasColumn('title', 'string', 255); $this->hasColumn('body', 'clob'); }

public function setUp()
{
    $this->actAs('Versionable', array(
            'versionColumn' => 'version',
            'className' => '%CLASS%Version',
            'auditLog' => true
        )
    );
}

}

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

BlogPost: actAs: Versionable: versionColumn: version className:

%CLASS%Version auditLog: true columns: title: string(255) body: clob

NOTE auditLogオプションはauditのログ履歴を無効にするために使われます。これはバージョン番号を維持したいがそれぞれのバージョンでのデータを維持したくない場合に使います。

上記のモデルで生成されたSQLをチェックしてみましょう:

// test.php

// ... $sql = Doctrine_Core::generateSqlFromArray(array('BlogPost')); echo $sql[0] . ""; echo $sql[1];

上記のコードは次のSQLクエリを出力します:

CREATE TABLE blog_post_version (id BIGINT, title VARCHAR(255), body

LONGTEXT, version BIGINT, PRIMARY KEY(id, version)) ENGINE = INNODB CREATE TABLE blog_post (id BIGINT AUTO_INCREMENT, title VARCHAR(255), body LONGTEXT, version BIGINT, PRIMARY KEY(id)) ENGINE = INNODB ALTER TABLE blog_post_version ADD FOREIGN KEY (id) REFERENCES blog_post(id) ON UPDATE CASCADE ON DELETE CASCADE

NOTE おそらく予期していなかったであろう2の追加ステートメントがあることに注目してください。ビヘイビアは自動的にblog\_post\_versionテーブルを作成しこれをblog_postに関連付けます。

BlogPostを挿入もしくは更新するときバージョンテーブルは古いバージョンのレコードをすべて保存していつでも差し戻しできるようにします。最初にNewsItemをインスタンス化するとき内部で起きていることは次の通りです:

• BlogPostVersionという名前のクラスが即座に作成される。レコードが指し示すテーブルはblog\_post_versionである
• BlogPostオブジェクトが削除/更新されるたびに以前のバージョンはblog\_post_versionに保存される
• BlogPostオブジェクトが更新されるたびにバージョン番号が増える。

BlogPostモデルで遊びましょう:

$blogPost = new BlogPost(); $blogPost->title = 'Test blog post';

$blogPost->body = 'test'; $blogPost->save();

$blogPost->title = 'Modified blog post title'; $blogPost->save();

print_r($blogPost->toArray());

上記の例では次の内容が出力されます:

$ php test.php Array ( [id] => 1 [title] => Modified blog post title

[body] => test [version] => 2 )

NOTE versionカラムの値が2であることに注目してください。2つのバージョンのBlogPostモデルを保存したからです。ビヘイビアが格納するrevert()メソッドを使用することで別のバージョンに差し戻すことができます。

最初のバージョンに差し戻してみましょう:

blogPost->revert(1); print_r(blogPost->toArray());

上記の例は次の内容を出力する:

$ php test.php Array ( [id] => 2 [title] => Test blog post [body] =>

test [version] => 1 )

NOTE versionカラムの値が1に設定されtitleはBlogPostを作成するときに設定されたオリジナルの値に戻ります。

Timestampable

Timestampableビヘイビアはcreated\_atとupdated_atカラムを追加しレコードが挿入と更新されたときに値を自動的に設定します。

日付を知ることは共通のニーズなのでBlogPostモデルを展開してこれらの日付を自動的に設定するためにTimestampableビヘイビアを追加します。

// models/BlogPost.php

class BlogPost extends Doctrine_Record { // ...

public function setUp()
{
    $this->actAs('Timestampable');
}

}

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

# schema.yml

BlogPost: actAs: # ... Timestampable: # ...

updated\_atフィールドではなくcreated_atタイムスタンプといったカラムの1つだけを使うことに興味があるのであれば、下記の例のようにフィールドのどちらかに対してdisabledをtrueに設定します。

BlogPost: actAs: # ... Timestampable: created: name: created_at type:

timestamp format: Y-m-d H:i:s updated: disabled: true # ...

新しい投稿を作成するときに何が起きるのか見てみましょう:

$blogPost = new BlogPost(); $blogPost->title = 'Test blog post';

$blogPost->body = 'test'; $blogPost->save();

print_r($blogPost->toArray());

上記の例は次の内容を出力します:

$ php test.php Array ( [id] => 1 [title] => Test blog post [body] =>

test [version] => 1 [created_at] => 2009-01-21 17:54:23 [updated_at] => 2009-01-21 17:54:23 )

NOTE created\_atとupdated_atの値が自動的に設定されることに注目してください！

ビヘイビアの作成側のTimestampableビヘイビアで使うことができるすべてのオプションのリストです:

||  名前 ||  デフォルト ||  説明 || || name || created_at || カラムの名前 || || type || timestamp || カラムの型 || || options || array() || カラム用の追加オプション || || format || Y-m-d H:i:s || timestampカラム型を使いたくない場合のタイムスタンプのフォーマット。日付はPHPの[http://www.php.net/date date()]関数で生成される || || disabled || false || 作成日を無効にするか || || expression || NOW() || カラムの値を設定するために使用する式 ||

作成側では不可能な更新側のビヘイビアでTimestampableビヘイビアで使うことができるすべてのオプションのリストは次の通りです:

||  名前 ||  デフォルト||  説明 || || onInsert ||true || レコードが最初に挿入されるときに更新日付を設定するか ||

Sluggable

Sluggableビヘイビアは素晴らしい機能の1つでタイトル、題目などのカラムから作成できる人間が読解できるユニークな識別子を保存するためにモデルにカラムを自動的に追加します。これらの値は検索エンジンにフレンドリーなURLに使うことができます。

投稿記事用のわかりやすいURLが欲しいのでSluggableビヘイビアを使うようにBlogPostモデルを拡張してみましょう:

// models/BlogPost.php

class BlogPost extends Doctrine_Record { // ...

public function setUp()
{
    // ...

    $this->actAs('Sluggable', array(
            'unique'    => true,
            'fields'    => array('title'),
            'canUpdate' => true
        )
    );
}

}

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

# schema.yml

BlogPost: actAs: # ... Sluggable: unique: true fields: [title] canUpdate: true # ...

新しい投稿を作成する際に何が起きるのか見てみましょう。slugカラムは自動的に設定されます:

$blogPost = new BlogPost(); $blogPost->title = 'Test blog post';

$blogPost->body = 'test'; $blogPost->save();

print_r($blogPost->toArray());

上記の例は次の内容を出力します:

$ php test.php Array ( [id] => 1 [title] => Test blog post [body] =>

test [version] => 1 [created_at] => 2009-01-21 17:57:05 [updated_at] => 2009-01-21 17:57:05 [slug] => test-blog-post )

NOTE titleカラムの値に基づいてslugカラムの値が自動的に設定されることに注目してください。スラッグが作成されるとき、デフォルトではurlizedが使われます。これはURLにフレンドリーではない文字は削除されホワイトスペースはハイフン(-)に置き換えられます。

uniqueフラグは作成されたスラッグがユニークであることを強制します。ユニークではない場合データベースに保存される前にauto incrementな整数がスラッグに自動的に追加されます。

canUpdateフラグはurlフレンドリーなスラッグを生成する際にユーザーが使用するスラッグを自動的に設定することを許可します。

Sluggableビヘイビアで使うことができるすべてのオプションのリストは次の通りです:

||  名前 ||  デフォルト||  説明 || || name || slug || スラッグカラムの名前 || || alias || null || スラッグカラムのエイリアス || || type || string || スラッグカラムの型 || || length || 255 || スラッグカラムの長さ || || unique || true || ユニークスラッグの値が強制されるかどうか || || options || array() || スラッグカラム用の他のオプション || || fields || array() || スラッグの値をビルドするために使用するフィールド || || uniqueBy || array() || ユニークスラッグを決定するフィールド || || uniqueIndex|| true || ユニークインデックスを作成するかどうか || || canUpdate || false || スラッグが更新できるかどうか || || builder || array('Doctrine_Inflector', 'urlize') || スラッグをビルドするために使うClass::method() || || indexName || sluggable || 作成するインデックスの名前 ||

I18n

Doctrine_I18nパッケージはレコードクラス用の国際化サポートを提供するビヘイビアです。次の例ではtitleとcontentの2つのフィールドを持つNewsItemクラスがあります。異なる言語サポートを持つtitleフィールドを用意したい場合を考えます。これは次のように実現できます:

class NewsItem extends Doctrine_Record { public function

setTableDefinition() { $this->hasColumn('title', 'string', 255); $this->hasColumn('body', 'blog'); }

public function setUp()
{
    $this->actAs('I18n', array(
            'fields' => array('title', 'body')
        )
    );
}

}

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

NewsItem: actAs: I18n: fields: [title, body] columns: title:

string(255) body: clob

I18nビヘイビアで使うことができるすべてのオプションのリストは次の通りです:

||  名前 ||  デフォルト ||  説明 || || className || %CLASS%Translation || 生成クラスに使う名前のパターン || || fields || array() || 国際化するフィールド || || type || string || langカラムの型 || || length || 2 || langカラムの長さ || || options || array() || langカラム用の他のオプション ||

上記のモデルで生成されるSQLをチェックしてみましょう:

// test.php

// ... $sql = Doctrine_Core::generateSqlFromArray(array('NewsItem')); echo $sql[0] . ""; echo $sql[1];

上記のコードは次のSQLを出力します:

CREATE TABLE news_item_translation (id BIGINT, title VARCHAR(255),

body LONGTEXT, lang CHAR(2), PRIMARY KEY(id, lang)) ENGINE = INNODB CREATE TABLE news_item (id BIGINT AUTO_INCREMENT, PRIMARY KEY(id)) ENGINE = INNODB

NOTE titleフィールドがnews_itemテーブルに存在しないことに注目してください。翻訳テーブルにあるとメインテーブルで同じフィールドが存在してリソースの無駄遣いになるからです。基本的にDoctrineは常にメインテーブルから翻訳されたフィールドをすべて削除します。

初めて新しいNewsItemレコードを初期化するときDoctrineは次の内容をビルドするビヘイビアを初期化します:

1. NewsItemTranslationと呼ばれるRecordクラス
2. NewsItemTranslationとNewsItemの双方向なリレーション

NewsItemの翻訳を操作する方法を見てみましょう:

// test.php

// ... $newsItem = new NewsItem(); $newsItem->Translation['en']->title = 'some title'; $newsItem->Translation['en']->body = 'test'; $newsItem->Translation['fi']->title = 'joku otsikko'; $newsItem->Translation['fi']->body = 'test'; $newsItem->save();

print_r($newsItem->toArray());

上記の例は次の内容を出力します:

$ php test.php Array ( [id] => 1 [Translation] => Array ( [en] => Array

( [id] => 1 [title] => some title [body] => test [lang] => en ) [fi] => Array ( [id] => 1 [title] => joku otsikko [body] => test [lang] => fi )

$ )

)

翻訳データをどのように読み取るのでしょうか？これは簡単です！すべての項目を見つけて翻訳を終わらせましょう:

// test.php

// ... $newsItems = Doctrine_Query::create() ->from('NewsItem n') ->leftJoin('n.Translation t') ->where('t.lang = ?') ->execute(array('fi'));

echo $newsItems[0]->Translation['fi']->title;

上記のコードは次の内容を出力します:

$ php test.php joku otsikko

NestedSet

NestedSetビヘイビアによってモデルを入れ子集合ツリー構造(nested set tree structure)に変換できます。ツリー構造全体を1つのクエリで効率的に読み取ることができます。このビヘイビアはツリーのデータを操作するための素晴らしいインターフェイスも提供します。

例としてCategoryモデルを考えてみましょう。カテゴリを階層ツリー構造で編成する必要がある場合は次のようになります:

// models/Category.php

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

public function setUp()
{
    $this->actAs('NestedSet', array(
            'hasManyRoots' => true,
            'rootColumnName' => 'root_id'
        )
    );
}

}

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

# schema.yml

Category: actAs: NestedSet: hasManyRoots: true rootColumnName: root_id columns: name: string(255)

上記のモデルで生成されたSQLをチェックしてみましょう:

// test.php

// ... $sql = Doctrine_Core::generateSqlFromArray(array('Category')); echo $sql[0];

上記のコードは次のSQLクエリを出力します:

CREATE TABLE category (id BIGINT AUTO_INCREMENT, name VARCHAR(255),

root_id INT, lft INT, rgt INT, level SMALLINT, PRIMARY KEY(id)) ENGINE = INNODB

NOTE root_id、lft、rgtとlevelカラムが自動的に追加されることに注目してください。これらのカラムはツリー構造を編成して内部の自動処理に使われます。

ここではNestedSetビヘイビアの100％を検討しません。とても大きなビヘイビアなので[doc hierarchical-data 専用の章]があります。

Searchable

Searchableビヘイビアは全文インデックス作成と検索機能を提供します。データベースとファイルの両方のインデックスと検索に使われます。

求人投稿用のJobモデルがあり簡単に検索できるようにすることを考えてみましょう:

// models/Job.php

class Job extends Doctrine_Record { public function setTableDefinition() { $this->hasColumn('title', 'string', 255); $this->hasColumn('description', 'clob'); }

public function setUp()
{
    $this->actAs('Searchable', array(
            'fields' => array('title', 'content')
        )
    );
}

}

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

Job: actAs: Searchable: fields: [title, description] columns: title:

string(255) description: clob

上記のモデルで生成されたSQLをチェックしてみましょう:

// test.php

// ... $sql = Doctrine_Core::generateSqlFromArray(array('Job')); echo $sql[0] . ""; echo $sql[1] . ""; echo $sql[2];

上記のコードは次のSQLクエリを出力します:

CREATE TABLE job_index (id BIGINT, keyword VARCHAR(200), field

VARCHAR(50), position BIGINT, PRIMARY KEY(id, keyword, field, position)) ENGINE = INNODB CREATE TABLE job (id BIGINT AUTO_INCREMENT, title VARCHAR(255), description LONGTEXT, PRIMARY KEY(id)) ENGINE = INNODB ALTER TABLE job_index ADD FOREIGN KEY (id) REFERENCES job(id) ON UPDATE CASCADE ON DELETE CASCADE

NOTE job\_indexテーブルおよびjobとjob_indexの間の外部キーが自動的に生成されることに注目してください。

Searchableビヘイビアは非常に大きなトピックなので、詳細は[doc searching :name]の章で見つかります。

Geographical

下記のコードはデモのみです。Geographicalビヘイビアは2つのレコードの間のマイルもしくはキロメータの数値を決定するためのレコードデータで使うことができます。

// models/Zipcode.php

class Zipcode extends Doctrine_Record { public function setTableDefinition() { $this->hasColumn('zipcode', 'string', 255); $this->hasColumn('city', 'string', 255); $this->hasColumn('state', 'string', 2); $this->hasColumn('county', 'string', 255); $this->hasColumn('zip_class', 'string', 255); }

public function setUp()
{
    $this->actAs('Geographical');
}

}

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

# schema.yml

Zipcode: actAs: [Geographical] columns: zipcode: string(255) city: string(255) state: string(2) county: string(255) zip_class: string(255)

上記のモデルで生成されたSQLをチェックしてみましょう:

// test.php

// ... $sql = Doctrine_Core::generateSqlFromArray(array('Zipcode')); echo $sql[0];

上記のコードは次のSQLクエリを出力します:

CREATE TABLE zipcode (id BIGINT AUTO_INCREMENT, zipcode VARCHAR(255),

city VARCHAR(255), state VARCHAR(2), county VARCHAR(255), zip_class VARCHAR(255), latitude DOUBLE, longitude DOUBLE, PRIMARY KEY(id)) ENGINE = INNODB

NOTE Geographicalビヘイビアが2つのレコードの距離を算出するために使われるレコードにlatitudeとlongitudeカラムを自動的に追加することに注目してください。使い方の例は下記の通りです。

最初に2つの異なるzipcodeレコードを読み取りましょう:

// test.php

// ... $zipcode1 = Doctrine_Core::getTable('Zipcode')->findOneByZipcode('37209'); $zipcode2 = Doctrine_Core::getTable('Zipcode')->findOneByZipcode('37388');

ビヘイビアが提供するgetDistance()メソッドを使用してこれら2つのレコードの間の距離を取得できます:

// test.php

// ... echo zipcode1->getDistance(zipcode2, $kilometers =false);

NOTE getDistance()メソッドの2番目の引数はキロメーターで距離を返すかどうかです。デフォルトはfalseです。

同じ市にはない50の近いzipcodeを取得してみましょう:

// test.php

// ... $q = $zipcode1->getDistanceQuery();

q->orderby('miles asc') ->addWhere(q->getRootAlias() . '.city!= ?', $zipcode1->city) ->limit(50);

echo $q->getSqlQuery();

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

SELECT z.id AS zid, z.zipcode AS zzipcode, z.city AS z**city,

z.state AS zstate, z.county AS zcounty, z.zip_class AS zzip\_class, z.latitude AS zlatitude, z.longitude AS zlongitude, ((ACOS(SIN(\* PI() / 180) \* SIN(z.latitude \* PI() / 180) + COS(\* PI() / 180) \* COS(z.latitude \* PI() / 180) \* COS((- z.longitude) \* PI() / 180)) \* 180 / PI()) \* 60 \* 1.1515) AS z0, ((ACOS(SIN(* PI() / 180) * SIN(z.latitude * PI() / 180) + COS(* PI() / 180) * COS(z.latitude * PI() / 180) * COS((- z.longitude) * PI() / 180)) * 180 / PI()) * 60 * 1.1515 * 1.609344) AS z**1 FROM zipcode z WHERE z.city != ? ORDER BY z__0 asc LIMIT 50

NOTE 上記のSQLクエリが書かなかったSQLの束を含んでいることに注目してください。これはレコードの間のマイル数を計算するためにビヘイビアによって自動的に追加されます。

クエリを実行して算出されたマイル数の値を使用します:

// test.php

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

foreach ($result as $zipcode) { echo $zipcode->city . " - " . $zipcode->miles . ""; // You could also access $zipcode->kilometers }

これをテストするためにサンプルのzipcodeを取得します

http://www.populardata.com/zip_codes.zip

csvファイルをダウンロードして次の関数でインポートしてください:

// test.php

// ... function parseCsvFile($file, $columnheadings = false, $delimiter = ',', $enclosure = """) { $row = 1; $rows = array(); handle = fopen(file, 'r'); .. code-block:

while (($data = fgetcsv($handle, 1000, $delimiter, $enclosure)) !== FALSE) {

    if (!($columnheadings == false) && ($row == 1)) {
        $headingTexts = $data;
    } elseif (!($columnheadings == false)) {
        foreach ($data as $key => $value) {
            unset($data[$key]);
            $data[$headingTexts[$key]] = $value;
        }
        $rows[] = $data;
    } else {
        $rows[] = $data;
    }
    $row++;
}

fclose($handle);
return $rows;

}

$array = parseCsvFile('zipcodes.csv', false);

foreach ($array as $key => $value) { $zipcode = new Zipcode(); zipcode->fromArray(value); $zipcode->save(); } ---------- SoftDelete ----------

SoftDeleteビヘイビアはdelete()機能をオーバーライドしdeletedカラムを追加するとてもシンプルだが大いにおすすめできるモデルビヘイビアです。delete()が呼び出されるとき、データベースからレコードを削除する代わりに、削除フラグを1にセットします。下記のコードはSoftDeleteビヘイビアでモデルを作る方法です。

// models/SoftDeleteTest.php

class SoftDeleteTest extends Doctrine_Record { public function setTableDefinition() { $this->hasColumn('name', 'string', null, array( 'primary' => true ) ); }

public function setUp()
{
    $this->actAs('SoftDelete');
}

}

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

# schema.yml

SoftDeleteTest: actAs: [SoftDelete] columns: name: type: string(255) primary: true

上記のモデルによって生成されたSQLをチェックしてみましょう:

// test.php

// ... $sql = Doctrine_Core::generateSqlFromArray(array('SoftDeleteTest')); echo $sql[0];

上記のコードは次のSQLクエリを出力します:

CREATE TABLE soft_delete_test (name VARCHAR(255), deleted TINYINT(1)

DEFAULT '0' NOT NULL, PRIMARY KEY(name)) ENGINE = INNODB

ビヘイビアを動かしてみましょう。

NOTE すべての実行されるクエリのためにDQLコールバックを有功にする必要があります。SoftDeleteビヘイビアにおいて追加のWHERE条件でdeleted_atフラグが設定されているすべてのレコードを除外するSELECT文をフィルタリングするために使われます。

DQLコールバックを有効にする

// bootstrap.php

// ... $manager->setAttribute(Doctrine_Core::ATTR_USE_DQL_CALLBACKS, true);

SoftDeleteの機能を実行できるように新しいレコードを保存します:

// test.php

// ... $record = new SoftDeleteTest(); $record->name = 'new record'; $record->save();

delete()を呼び出すときdeletedフラグがtrueにセットされます:

// test.php

// ... $record->delete();

print_r($record->toArray());

上記の例は次の内容を出力します:

$ php test.php Array ( [name] => new record [deleted] => 1 )

また、クエリを行うとき、deletedがnullではないレコードは結果から除外されます:

// test.php

// ... $q = Doctrine_Query::create() ->from('SoftDeleteTest t');

echo $q->getSqlQuery();

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

SELECT s.name AS sname, s.deleted AS sdeleted FROM

soft_delete_test s WHERE (s.deleted = ? OR s.deleted IS NULL)

NOTE 削除されていないレコードだけを返すためにwhere条件が自動的に追加されたことに注目してください。

クエリを実行する場合:

// test.php

// ... $count = $q->count(); echo $count;

上記のコード0をechoします。deleteフラグが設定されたので保存されたレコードが除外されます。