実際の世界のアプリケーションでは、データベースからコンテンツを表示するのは共通のタスクです。またコンテンツが何千もの項目を含む検索結果である場合を想像してください。うたがいなく、巨大なリストになり、メモリーの消費量が多くなりユーザーは正しい項目を見つけづらくなります。この問題に対してコンテンツ表示の編成が必要でページ分割が手助けになります。

Doctrineは高度で柔軟なページャーパッケージを実装します。これによってリストを複数のページに分割できるだけでなく、ページリンクのレイアウトもコントロールできます。この章では、ページャーオブジェクトの作り方、ページャースタイルをコントロール仕方を学び、最後にページャーレイアウトオブジェクト - Doctrineの強力なページリンク表示機能の概要を見ます。

クエリのページ分割はクエリ自身と同じぐらいシンプルで効率的にできます。Doctrine_Pagerはクエリを処理してページ分割することを担います。次の小さなピースのコードで確認しましょう:

// 初期値を定義する
$currentPage = 1;
$resultsPerPage = 50;

// ページャーオブジェクトを作成する
$pager = new Doctrine_Pager(
      Doctrine_Query::create()
            ->from( 'User u' )
            ->leftJoin( 'u.Group g' )
            ->orderby( 'u.username ASC' ),
      $currentPage, // リクエストの現在のページ
      $resultsPerPage // (オプション)ページごとの結果数。デフォルトは25
);

この場所までは、このコードは古いDoctrine_Queryオブジェクトと同じです。唯一の違いは新しい2つの引数が存在することです。これら2の引数に加えて古いクエリオブジェクトはDoctrine_Pagerオブジェクトによってカプセル化されます。この段階では、Doctrine_Pagerはページ分割をコントロールするために必要な基本データを定義します。ページャーの実際のステータスを知りたい場合、行うべきことはこれが既に実行されたかどうかチェックすることです:

$pager->getExecuted();

Doctrine_Pagerによって提供される任意のメソッドにアクセスしようとする場合、Pagerがまだ実行されなかったことを報告するDoctrine_Pager_Exceptionが投げられるのを経験することになります。実行されたとき、Doctrine_Pagerは情報を検索する強力なメソッドを提供します。APIの使い方はこのトピックの最後に並べてあります。

クエリを実行するには、プロセスは現存するDoctrine_Query実行呼び出しと似ています。オプションのパラメータを含む構文の完全な例は次の通りです:

$items = $pager->execute([$args = array() [, $fetchType = null]]);

foreach ($items as $item) {
    // ...
}

レコードクエリがカウンタークエリと異なる特別なケースがあります。この状況に対応するために、Doctrine_Pagerにはカウントしてから実行できるようにするメソッドがあります。最初に行わなければならないのはカウントクエリを定義することです:

$pager->setCountQuery($query [, $params = null]);

// ...

$rs = $pager->execute();

setCountQueryの最初のパラメータは有効なDoctrine_QueryオブジェクトかDQL文字列です。2番目の引数はカウンタークエリに送信されるオプションパラメータです。このパラメータを定義しないので、後でsetCountQueryParamsを呼び出して定義することができます:

$pager->setCountQueryParams([$params = array() [, $append = false]]);

このメソッドは2つのパラメータを受けとります。最初のパラメータはカウントパラメータに送信されるもので2番目のパラメータは$paramsがリストに追加されるもしくはカウントクエリパラメータがオーバーライドされるかどうかです。デフォルトのビヘイビアはリストをオーバーライドします。カウントクエリに関して最後に言うことは、カウントクエリ用のパラメータを定義しない場合、$pager->execute()の呼び出しで定義するパラメータを送り出すことができます。

カウントクエリは常にアクセスできます。これを定義して$pager->getCountQuery()を呼び出す場合、"取得(fetcher)"クエリが返されます。

Doctrine_Pagerが提供する他の機能にアクセスする必要がある場合、APIを通してアクセスできます:

// Pagerが既に実行されたかのチェックを返す
$pager->getExecuted();

// クエリ検索で見つかるアイテムの合計数を返す
$pager->getNumResults();

// 最初のページを返す(常に1)
$pager->getFirstPage();

// ページの合計数を返す
$pager->getLastPage();

// 現在のページを返す
$pager->getPage();

// 現在の新しいページを定義する(実行を再度呼び出してオフセットと値を調整する必要がある)
$pager->setPage($page);

// 次のページを返す
$pager->getNextPage();

// 前のページを返す
$pager->getPreviousPage();

// 現在のページの最初のインデックスを返す
$pager->getFirstIndice();

// 現在のページの最後のインデックスを返す
$pager->getLastIndice();

// ページ分割をする必要がある場合はtrueそうでなければfalseを返す
$pager->haveToPaginate();

// ページごとの最大数を返す
$pager->getMaxPerPage();

// ページごとのレコードの最大数を定義する(再度呼び出してオフセットと値を調整する必要がある)
$pager->setMaxPerPage($maxPerPage);

// 現在のページのアイテム数を返す
$pager->getResultsInPage();

// カウント結果をページャーにするために使われるDoctrine_Queryオブジェクトを返す
$pager->getCountQuery();

// ページャーによって使われるカウンタクエリを定義する
$pager->setCountQuery($query, $params = null);

// Doctrine_Queryカウントによって使われるパラメータを返す(パラメータが定義されていない場合$defaultParamsを返す)
$pager->getCountQueryParams($defaultParams = array());

// Doctrine_Queryカウンタによって使われるパラメータを定義する
$pager->setCountQueryParams($params = array(), $append = false);

// Doctrine_Queryオブジェクトを返す
$pager->getQuery();

// 関連するDoctrine_Pager_Range_* インスタンスを返す
$pager->getRange($rangeStyle, $options = array());

シンプルなページ分割では不十分なケースがあります。1つの例はページリンクのリストを書くときです。ページャーを越えるより強力なコントロール機能を有効にするために、レンジを作ることを可能にするページャーパッケージの小さなサブセットがあります。

現在Doctrineは2種類(2つのスタイル)のレンジ: スライディング(Doctrine_Pager_Range_Sliding)とジャンピング(Doctrine_Pager_Range_Jumping)を実装します。

これまで、ページ分割と現在のページ周辺のレンジを読み取る方法を学びました。ページリンク生成を含むビジネスロジックを抽象化するために、Doctrine_Pager_Layoutと呼ばれる強力なコンポーネントがあります。このコンポーネントのメインのアイディアはPHPロジックを抽象化してHTMLをDoctrineの開発者に定義させることです。

Doctrine_Pager_Layoutは必須の引数を3つ受け取ります: a Doctrine_Pagerインスタンス、Doctrine_Pager_Rangeサブクラスインスタンスとテンプレートの{%url}マスクとして割り当てられるURLを含む文字列です。ご覧の通り、Doctrine_Pager_Layoutの"変数"が2種類あります:

Doctrine_Pager_Layoutは本当に良い仕事をしますが、ときに十分ではないことがあります。次のようなページ分割のレイアウトを作らなければならない状況を考えてみましょう:

<< < 1 2 3 4 5 > >>

現在、生のDoctrine_Pager_Layoutでは不可能ですが、このクラスを継承して利用可能なメソッドを使えば実現可能です。基底レイアウトクラスは独自の実装を作成するために使われるメソッドを提供します。内容は次の通りです:

// $thisはDoctrine_Pager_Layoutのインスタンスを参照する

// マスクの置き換えを定義する。テンプレートを解析するとき、置き換えマスクを
// 新しいもの(もしくは値)に変換する。即座にマスクを変更できます
$this->addMaskReplacement($oldMask, $newMask, $asValue = false);

// マスク置き換えを削除する
$this->removeMaskReplacement($oldMask);

// すべてのマスク置き換えを削除する
$this->cleanMaskReplacements();

// テンプレートを解析し処理されたページの文字列を返す
$this->processPage($options = array()); // 少なくとも配列$optionsのpage_numberで必要

// Protectされたメソッドであるが、とても便利

// 渡されたページのテンプレートを解析し処理されたテンプレートを返す
$this->_parseTemplate($options = array());

// 送られたオプションによって正しいテンプレートを返すようにURLマスクを解析する
// 既に割り当てられたマスク置き換えを処理する
$this->_parseUrlTemplate($options = array());

// 与えられたページのマスク置き換えを解析する
$this->_parseReplacementsTemplate($options = array());

// 与えられたページのURLマスクを解析し処理されたURLを返す
$this->_parseUrl($options = array());

// 置き換え予定のマスクを新しいマスク/値に変更して、マスク置き換えを解析する
$this->_parseMaskReplacements($str);

Doctrine_Pager_Layoutを継承するとき便利で小さなメソッドがあるので、実装されたクラスを見てみましょう:

class PagerLayoutWithArrows extends Doctrine_Pager_Layout
{
    public function display($options = array(), $return = false)
    {
        $pager = $this->getPager();
        $str = '';

        // 最初のページ
        $this->addMaskReplacement('page', '«', true);
        $options['page_number'] = $pager->getFirstPage();
        $str .= $this->processPage($options);

        // 以前のページ
        $this->addMaskReplacement('page', '‹', true);
        $options['page_number'] = $pager->getPreviousPage();
        $str .= $this->processPage($options);

        // ページの一覧
        $this->removeMaskReplacement('page');
        $str .= parent::display($options, true);

        // 次のページ
        $this->addMaskReplacement('page', '›', true);
        $options['page_number'] = $pager->getNextPage();
        $str .= $this->processPage($options);

        // 最後のページ
        $this->addMaskReplacement('page', '»', true);
        $options['page_number'] = $pager->getLastPage();
        $str .= $this->processPage($options);

        // スクリーンに表示する代わりに値を返すことが可能
        if ($return) {
            return $str;
        }

        echo $str;
    }
}

ご覧の通り、<<、<、>と>>のアイテムを手動で処理しなければなりません。生の値を設定することで{%page}マスクをオーバーライドします(生の値は3番目のパラメータをtrueとして設定します)。それからページを処理する必須情報のみを定義しこれを呼び出します。戻り値は文字列として処理されたテンプレートです。これをカスタムボタンにします。

これで全体的に異なる状況をサポートでいます。Doctrineは透過的なフレームワークですが、多くのユーザーはsymfonyと一緒に使います。Doctrine_Pagerとサブクラスはsymfonyと100%互換性がありますが、Doctrine_Pager_Layoutはsymfonyのlink_toヘルパー関数と連携するために調整が必要です。Doctrine_Pager_Layoutでこれを使うことができるようにするにはこのクラスを継承しカスタムプロセッサーを追加しなければなりません。例として(symfonyと連携させる場合)、{link_to}...{/link_to}をテンプレートプロセッサーとして使います。継承クラスとsymfonyでの使い方は次の通りです:

class sfDoctrinePagerLayout extends Doctrine_Pager_Layout
{
    public function __construct($pager, $pagerRange, $urlMask)
    {
        sfLoader::loadHelpers(array('Url', 'Tag'));
        parent::__construct($pager, $pagerRange, $urlMask);
    }

    protected function _parseTemplate($options = array())
    {
        $str = parent::_parseTemplate($options);

        return preg_replace(
            '/\{link_to\}(.*?)\{\/link_to\}/', link_to('$1', $this->_parseUrl($options)), $str
        );
    }
}

使い方:

$pagerLayout = new sfDoctrinePagerLayout(
    $pager,
    new Doctrine_Pager_Range_Sliding(array('chunk' => 5)),
    '@hostHistoryList?page={%page_number}'
);

$pagerLayout->setTemplate('[{link_to}{%page}{/link_to}]');

Doctrineは接続からデータベースを作成したり削除する機能を提供します。これを使うためのしかけはDoctrineの接続名がデータベースの名前でなければならないことです。これが必須なのはPDOは接続するデータベースの名前を読み取るメソッドを提供しないことによります。データベースの作成と削除をできるようにするにはDoctrine自身がデータベースの名前を認識できなければなりません。

Doctrineはメインクラスで利用可能なスタティックなコンビニエンスメソッドを提供します。これらのメソッドはDoctrineの最もよく使われる複数の機能を1つのメソッドで実行します。これらのメソッドの大半はDoctrine_Taskシステムを使用します。これらのタスクはDoctrine_Cliからも実行されます。

// デバッグモードをon/offに切り替えこれがon/offであるかチェックする
Doctrine_Core::debug(true);

if (Doctrine_Core::debug() {
    echo 'debugging is on';
} else {
    echo 'debugging is off';
}

// Doctrineライブラリへのパスを取得する
$path =  Doctrine_Core::getPath();

// Doctrineライブラリへのパスがデフォルトの位置ではない場合パスをセットする
Doctrine_Core::setPath('/path/to/doctrine/libs');

// Doctrineと連携させるためにモデルをロードする
// 発見されロードされたDoctrine_Recordsの配列を返す
$models = Doctrine_Core::loadModels('/path/to/models', Doctrine_CoreMODEL_LOADING_CONSERVATIVE); // or Doctrine_Core::MODEL_LOADING_AGGRESSIVE
print_r($models);

// ロードされたすべてのモデルの配列を取得する
$models = Doctrine_Core::getLoadedModels();

// クラスの配列を上記のメソッドに渡しDoctrine_Recordsではないものを除去する
$models = Doctrine_Core::filterInvalidModels(array('User', 'Formatter', 'Doctrine_Record'));
print_r($models); // FormatterとDoctrine_Recordが有効ではないのでarray('User')を返す

// 実際のテーブル名用のDoctrine_Connectionオブジェクトを取得する
$conn = Doctrine_Core::getConnectionByTableName('user'); // テーブル名が関連する接続オブジェクトを返す
with.

// 既存のデータベースからYAMLスキーマを生成する
Doctrine_Core::generateYamlFromDb('/path/to/dump/schema.yml', array('connection_name'), $options);

// 既存のデータベースからモデルを生成する
Doctrine_Core::generateModelsFromDb('/path/to/generate/models', array('connection_name'), $options);

// オプションとデフォルト値の配列
$options = array('packagesPrefix'        =>  'Package',
                 'packagesPath'          =>  '',
                 'packagesFolderName'    =>  'packages',
                 'suffix'                =>  '.php',
                 'generateBaseClasses'   =>  true,
                 'baseClassesPrefix'     =>  'Base',
                 'baseClassesDirectory'  =>  'generated',
                 'baseClassName'         =>  'Doctrine_Record');

// YAMLスキーマからモデルを生成する
Doctrine_Core::generateModelsFromYaml('/path/to/schema.yml', '/path/to/generate/models', $options);

// 配列で提供されるテーブルを作成する
Doctrine_Core::createTablesFromArray(array('User', 'Phoneumber'));

// 既存のモデルセットからすべてのテーブルを作成する
// ディレクトリが渡されなければロードされたすべてのモデル用のSQLを生成する
Doctrine_Core::createTablesFromModels('/path/to/models');

// 既存のモデルのセットからSQLコマンドの文字列を生成する
// ディレクトリが渡されなければロードされたすべてのモデル用のSQLを生成する
Doctrine_Core::generateSqlFromModels('/path/to/models');

// 渡されたモデルの配列を作成するSQL文の配列を生成する
Doctrine_Core::generateSqlFromArray(array('User', 'Phonenumber'));

// 既存のモデルセットからYAMLスキーマを生成する
Doctrine_Core::generateYamlFromModels('/path/to/schema.yml', '/path/to/models');

// 接続用のすべてのデータベースを作成する
// 接続名の配列はオプション
Doctrine_Core::createDatabases(array('connection_name'));

// 接続に対するすべてのデータベースを削除する
// 接続名の配列はオプション
Doctrine_Core::dropDatabases(array('connection_name'));

// モデル用のすべてのデータをYAMLフィクスチャファイルにダンプする
// 2番目の引数はbool値でそれぞれのモデルに大して個別のフィクスチャファイルを生成するかどうか
// trueの場合ファイルの代わりにフォルダを指定する必要がある
Doctrine_Core::dumpData('/path/to/dump/data.yml', true);

// YAMLフィクスチャファイルからデータをロードする
// 2番目の引数はブール値でロードするときにデータを追加するかロードする前にすべてのデータを最初に削除するか
Doctrine_Core::loadData('/path/to/fixture/files', true);

// マイグレーションクラスのセット用のマイグレーション処理を実行する
$num = 5; // バージョン #5にマイグレートする
Doctrine::migration('/path/to/migrations', $num);

// 空白のマイグレーションクラスのテンプレートを生成する
Doctrine_Core::generateMigrationClass('ClassName', '/path/to/migrations');

// 既存のデータベース用のすべてのマイグレーションクラスを生成する
Doctrine_Core::generateMigrationsFromDb('/path/to/migrations');

// 既存のモデルのセット用のすべてのマイグレーションクラスを生成する
// 2番目の引数はloadModels()を使用して既にモデルをロードしている場合のオプション
Doctrine_Core::generateMigrationsFromModels('/path/to/migrations', '/path/to/models');

// モデル用のDoctrine_Tableインスタンスを取得する
$userTable = Doctrine_Core::getTable('User');

// Doctrineを単独のPHPファイルにコンパイルする
$drivers = array('mysql'); //コンパイルされたバージョンに含めたいドライバの配列を指定する
Doctrine_Core::compile('/path/to/write/compiled/doctrine', $drivers);

// デバッグ用にDoctrineオブジェクトをダンプする
$conn = Doctrine_Manager::connection();
Doctrine_Core::dump($conn);

タスクはコアのコンビニエンスメソッドを搭載するクラスです。必須の引数を設定することでタスクを簡単に実行できます。これらのタスクはDoctrineコマンドラインインターフェイスで直接使われます。

BuildAll
BuildAllLoad
BuildAllReload
Compile
CreateDb
CreateTables
Dql
DropDb
DumpData
Exception
GenerateMigration
GenerateMigrationsDb
GenerateMigrationsModels
GenerateModelsDb
GenerateModelsYaml
GenerateSql
GenerateYamlDb
GenerateYamlModels
LoadData
Migrate
RebuildDb

独自スクリプトでDoctrine Tasksを単独で実行する方法は下記の通りです。

Doctrine_Cliはタスクのコレクションで開発とテストの手助けをしてくれます。このマニュアルの典型例に関して、必要なタスクを実行するためにPHPスクリプトをセットアップします。このcliツールはこれらのタスクのためにそのまま使えることを目的としています。

Doctrineの実装を管理するために利用できるタスクの一覧は下記の通りです。

$ ./doctrine
Doctrine Command Line Interface

./doctrine build-all
./doctrine build-all-load
./doctrine build-all-reload
./doctrine compile
./doctrine create-db
./doctrine create-tables
./doctrine dql
./doctrine drop-db
./doctrine dump-data
./doctrine generate-migration
./doctrine generate-migrations-db
./doctrine generate-migrations-models
./doctrine generate-models-db
./doctrine generate-models-yaml
./doctrine generate-sql
./doctrine generate-yaml-db
./doctrine generate-yaml-models
./doctrine load-data
./doctrine migrate
./doctrine rebuild-db

CLI用のタスクは独立しており単独で使うことができます。下記のコードは例です。

$task = new Doctrine_Task_GenerateModelsFromYaml();

$args = array('yaml_schema_path' => '/path/to/schema',
              'models_path'      => '/path/to/models');

$task->setArguments($args);

try {
  if ($task->validate()) {
    $task->execute();
  }
} catch (Exception $e) {
  throw new Doctrine_Exception($e->getMessage());
}

"doctrine"という名前のファイルを実行可能にします。

#!/usr/bin/env php
[php]

chdir(dirname(__FILE__));
include('doctrine.php');

?>

Doctrine_Cliを実装する実際の"doctrine.php"という名前のPHPファイルは次の通りです。

// Doctrineの設定/セットアップ、接続、モデルなどを含める

// Doctrine Cliを設定する
// 通常cliタスクの引数がありますがここで設定すれば引数は自動的に入力されスクリプト実行時に入力する必要がなくなる

$config = array('data_fixtures_path'  =>  '/path/to/data/fixtures',
                'models_path'         =>  '/path/to/models',
                'migrations_path'     =>  '/path/to/migrations',
                'sql_path'            =>  '/path/to/data/sql',
                'yaml_schema_path'    =>  '/path/to/schema');

$cli = new Doctrine_Cli($config);
$cli->run($_SERVER['argv']);

これで次のようにコマンドを実行できます。

./doctrine generate-models-yaml
./doctrine create-tables

http://www.doctrine-project.org/download からもしくはsvnリポジトリから特別なサンドボックスをインストールできます。

svn co http://www.doctrine-project.org/svn/branches/0.11 doctrine
cd doctrine/tools/sandbox
chmod 0777 doctrine

./doctrine

上記のステップによってサンドボックスのcliが実行できるようになります。引数無しで./doctrineコマンドを実行すると利用可能なすべてのcliタスクのインデックスが表示されます。