独自のデータソース
導入
既存のドライバの中に要件を満たすものがない場合は、 独自のデータソースドライバを書くことになります。 これはとても簡単に行うことができ、非常に柔軟性が高くなります。
風変わりなソースからデータを取得する場合に 独自のドライバを書く必要があるのは当然ですが、 それ以外にも、特にデータベースなど (それに限りませんが) へのアクセスを最適化するといった目的でも独自のドライバを書くことがあります。
このドキュメントでは、データソースのインターフェイスとその実装方法を説明します。
用語定義
データソースドライバ は、 Structures_DataGrid_DataSource クラスを継承したものです。 これは データソースインターフェイス を実装しています。
データソース は、 データソースドライバ と同じ意味で使用します。
データソースインターフェイス には、 ドライバがオーバーロードするメソッド群が含まれます。また、 ドライバが使用できる protected なプロパティや推奨する実装が含まれます。
データソースコンテナ は定数あるいは任意の型 (string, array, object など) の変数で、データ自身あるいはデータの取得方法が含まれます。
すべての データソースドライバ は、 指定した データソースコンテナ に固有のもので、 そのコンテナを処理する方法を知っています。
データソースのインターフェイス
ドライバのプロパティ
array $_options - データをバインドした際のオプションが 連想配列で含まれます。このプロパティの内容を読み込むことはできますが、 直接書き換えてはいけません。
ドライバで実装しなければならない (あるいはすることのできる) メソッド
constructor (
( void
)
コンストラクタでは、もしデフォルトのオプションがあればそれを設定する必要があります。 その後で親クラスのコンストラクタをコールします。このメソッドは必須ではありません。
object bind (
mixed container
, array options
)
bind() は、データソースの container をドライバに読み込みます。その際に options を適用します。このメソッドは必須ではありません。 失敗した場合には PEAR_Error オブジェクトを返す必要があります。
object count (
( void
)
count() は、コンテナ内のレコード総数を返します。 このメソッドは必須で、fetch() の前に常にコールされます。 失敗した場合には PEAR_Error オブジェクトを返す必要があります。
object sort (
mixed sortSpec
, array sortDir
)
sort() は、 sortSpec およびオプションの sortDir にしたがってデータを並べ替えます。 このメソッドは必須で、fetch() の前に常にコールされます。 失敗した場合には PEAR_Error オブジェクトを返す必要があります。
mixed fetch (
integer offset
, integer len
)
fetch() は二次元の配列でデータを返さなければなりません。 返されるデータは offset で指定した場所のレコードから始まり、 len で指定した件数を含みます。このメソッドは必須です。 失敗した場合には PEAR_Error オブジェクトを返す必要があります。
ドライバが使用できる protected メソッド群
void _addDefaultOptions (
array options
)
_addDefaultOptions() は、 もしドライバ固有のオプションがある場合に、そのオプションとデフォルト値を指定します。 これはコンストラクタからコールされなければなりません。
void setOptions (
array options
)
setOptions() は、オプションを設定するために使用する public メソッドです。オプションを変更したい場合に、 ドライバはこのメソッドを使用します。
シンプルなドライバ
まずはシンプルなドライバからはじめてみましょう。そのほうが、読んで理解しやすいでしょう。 こんな SQL クエリのために独自のドライバを書くのは実用的ではありませんが、 はじめの一歩としてはお勧めです。
シンプルな SQL アダプタ
<?php
require 'Structures/DataGrid/DataSource.php';
require_once 'DB.php';
class MyDataSource extends Structures_DataGrid_DataSource {
var $db;
var $orderBy = '';
function MyDataSource() {
$dsn = 'mysql://someuser:apasswd@localhost/thedb';
$this->db =& DB::connect($dsn);
}
function count() {
$query = "SELECT COUNT(*) FROM animals WHERE species='cat'";
return $this->db->getOne($query);
}
function sort($sortSpec, $sortDir = 'ASC') {
$this->orderBy = "ORDER BY $sortSpec $sortDir";
}
function fetch($offset = 0, $len = null) {
$limit = is_null($len) ? "LIMIT $offset,18446744073709551615"
: "LIMIT $offset,$len";
$query = "SELECT * FROM animals WHERE species='cat' ";
$query .= $this->_orderBy . " $limit";
return $this->db->getAll($query);
}
}
?>
ドライバのテスト
実際に使用する前に dump() メソッドでドライバをテストしてみることをお勧めします。
dump() によるテスト
<?php
$datasource = new MyDataSource();
$count = $datasource->count();
echo "農場には $count 匹の猫がいます\n\n";
$datasource->sort('weight');
echo "一番軽いほうから 5 匹を表示します。\n";
// dump() は $offset および $len を fetch() と同じように受け付けます
$datasource->dump(0,5);
?>
このメソッドは、次のようにきれいに整形されたテキストのテーブルを出力します。
農場には 23 匹の猫がいます
一番軽いほうから 5 匹を表示します。
+---------+---------+-----------+--------+
| name | species | birthDate | weight |
+---------+---------+-----------+--------+
| sarge | cat | 20021220 | 1.8 |
| etch | cat | 20000509 | 2.5 |
| potato | cat | 19980128 | 3.8 |
| sid | cat | 20011101 | 4.1 |
| woody | cat | 19970712 | 6.0 |
+---------+---------+-----------+--------+
新しいドライバの使用法
さあ、これであなた専用のドライバができあがり、テストも完了しました。 そろそろ Structures_DataGrid で使用してみましょう。
そのためには、 bindDataSource() メソッドを使用します。
独自のデータソースのバインド
<?php
$datagrid =& new Structures_DataGrid();
$datasource = new MyDataSource();
$datagrid->bindDataSource($datasource);
$datagrid->render();
?>
これは、並べ替えのできる HTML テーブルを出力します。
もちろん、それ以外の Structures_DataGrid の機能も使用可能です。 例えばページ処理をしたり、XML や MS-Excel などの別のフォーマットで出力したりなどができます。
忘却曲線を使ってこの知識を確実に記憶に残す
