DB_Table クラスのチュートリアル

カラムの定義

$col プロパティは連想配列で、各キーがカラム名を表します。 キーに対応する値も連想配列で、ここにカラムの定義を指定します。 カラム定義の中の必須要素 'type' の値は DB_Table の データ型 の名前である必要があります。たとえば 'integer'、'decimal'、'boolean' などです。 文字列型である 'char' および 'varchar'、数値型である 'decimal' には、 さらに 'size' 要素も必須となります。これは整数値で、文字数あるいは桁数を指定します。 また、'decimal' 型の場合は 'scope' 要素も必須です。 これは、小数点以下の桁数を表します。'require' 要素に true を指定すると、SQL における NOT NULL と同じ意味になり、 このカラムには NULL 値を格納できなくなります。

例として、GuestBook テーブルを作成することを考えてみましょう。 このテーブルには、訪問者の姓と名、メールアドレス、 そして書き込み日時を記録するものとします。さらに、 各行に一意な ID を与える必要があります。 このテーブルのカラムは次のようになるでしょう。

• id -- 各行で一意な整数値 (必須。つまり null は許可しない)。

• fname -- 最大 32 文字までの文字列。訪問者の名前。

• lname -- 最大 64 文字までの文字列。訪問者の姓。

• email -- 最大 255 文字までの文字列。訪問者のメールアドレス (必須。つまり null は許可しない)。

• signdate -- 訪問者が書き込んだ日付 (必須。つまり null は許可しない)。

これらのカラム定義はプロパティ配列 $col で行う必要があります。 以下に、GuestBook_Table という名前の DB_Table サブクラスにおける $col の宣言の例を示します。これが、データベースの GuestBook テーブルに対応するものとなります。

例 39-1GuestBook のカラム定義 <?php class GuestBook_Table extends DB_Table { var $col = array( // 一意な行 ID 'id' => array( 'type' => 'integer', 'require' => true ), // 名前 'fname' => array( 'type' => 'varchar', 'size' => 32 ), // 姓 'lname' => array( 'type' => 'varchar', 'size' => 64 ), // メールアドレス 'email' => array( 'type' => 'varchar', 'size' => 128, 'require' => true ), // 書き込み日 'signdate' => array( 'type' => 'date', 'require' => true) ); ?>

インデックスの定義

プロパティ配列 $idx を使用してインデックスを宣言します。個々のインデックスは 'primary'、'unique' あるいは 'normal' のいずれかの型で宣言します。 primary や unique を指定した場合、そのキーの値はテーブル内で一意でなければならなくなります。 normal は、単に効率を上げるためだけのインデックスです。 単一カラムのインデックスおよび複数カラムのインデックスのどちらでも定義できます。

今回の例の GuestBook では、単一カラムのインデックスをふたつ作成します。まず最初は "id" カラムに対する主キーインデックスです。もうひとつは、"signdate" カラムに通常のインデックスを作成します。訪問者を日付や時刻で検索することがあると想定されるからです。 この場合の $idx プロパティの宣言は以下のようになります。

例 39-2GuestBook のインデックス定義 <?php class GuestBook_Table extends DB_Table { // カラムの定義については上を参照ください // var $col = array(...); // インデックスの定義 var $idx = array( 'id' => array( 'type' => 'primary', 'cols' => 'id' ), 'signdate' => array( 'type' => 'normal', 'cols' => 'signdate' ) ); } ?>

$idx 配列における各要素のキーがインデックス名となります。 対応する値は一般的には配列となり、そのインデックスの定義がここに格納されます。 インデックスの定義配列には 'type' と 'cols' の 2 つの要素が必ず存在します。 'type' の値は 'primary'、'unique' あるいは 'normal' のいずれかとなります。 'cols' 要素の値は、単一のカラム名か単一カラム名の配列、 あるいは複数のカラム名を含む配列のいずれかとなります。 単一カラムのインデックスについては別の省略形もありますが、 それはあとで説明します。

複数カラムのインデックスの例として、fname と lname カラムに対するインデックス "namefl" を定義してみます。

例 39-3複数カラムのインデックスの定義 <?php class GuestBook_Table extends DB_Table { // カラムの定義 // var $col = array( ... ) // インデックスの定義 var $idx = array( // さきほどの単一カラムのインデックスに加え、 'namefl' = array( 'type' => 'normal', 'cols' => array('fname', 'lname') ) ); } ?>

単一カラムのインデックスをお手軽に宣言するための方法も準備されています。 カラム名と同じ名前で単一カラムのインデックスを作成したい場合は、 カラム名を $idx のキーにしてそのインデックスの型を表す文字列 (定義配列ではありません) を値にします。

例 39-4単一カラムインデックスを簡単に定義する方法 <?php class GuestBook_Table extends DB_Table { // カラムの定義 // var $col = array(...); // インデックスの定義 var $idx = array( // 主キーインデックス 'id' を、'id' カラムに定義します 'id' => 'primary', // 通常のインデックス 'signdate' を、'signdate' カラムに定義します 'signdate' => 'normal' ); } ?>

自動インクリメントのカラムの宣言

各テーブルについてひとつの整数型カラムを、 自動インクリメントのカラムとして宣言することができます。 このカラムは、通常は主キーとなります。この宣言をすることによって変化するのは、 insert() メソッドの振る舞いだけです。 insert() メソッドを実行する際に 自動インクリメントのカラムを省略したり NULL を渡したりすると、 自動生成された整数値が挿入されます。

あるカラムを自動インクリメントとして設定するには、 $auto_inc_col プロパティの値にそのカラムの名前を指定します。次の例では、 GuestBook テーブルの主キーカラムである "id" を自動インクリメントに設定します。

<?php

class GuestBook_Table extends DB_Table
{
    
    // カラムの定義
    // var $col = array(...);
       
    // インデックスの定義
    var $idx = array(...);

    // 自動インクリメントの宣言
    var $auto_inc_col = 'id';

}

?>

行の追加

GuestBook テーブルに行を追加するには、 insert() メソッドを使用します。 このメソッドに渡すパラメータは連想配列で、 そのキーがカラム名、そして追加する値をキーに関連づけます。

例 39-7行の追加 <?php // [省略] $GuestBook オブジェクトを作成します // フィールドとその値を関連づけます $row = array( 'fname' => 'Thomas', 'lname' => 'Anderson', 'signdate' => '2003-10-12', 'email' => 'neo@matrix.net' ); // テーブルに追加し、結果を表示します $result = $GuestBook->insert($row); if (PEAR::isError($result)) { // エラー処理コード } ?>

デフォルトでは、insert メソッドは自動的にデータ型の検証を行います。 また、自動インクリメントカラム以外の必須カラムについてのデータが存在するかどうかも調べます。 これらの検証に失敗した場合は、このメソッドは PEAR Error を返し、データの追加は行いません。 上の例では必須カラム 'id' の値を指定していませんが、 これは 'id' カラムが自動インクリメント型だからです。 詳しくは以下で説明します。

自動インクリメントカラムおよびシーケンス

DB_Table は、 DB あるいは MDB2 が作成したシーケンスを使用して自動インクリメントの整数型の ID を生成することができます。insert メソッドで 自動インクリメント型のカラムの値が設定されていなかったり PHP の NULL が設定されていたりした場合は、 自動インクリメントのシーケンスの値を使用してそのカラムにデータを追加します。 上の例では、'id' カラムに対して、 シーケンスの値を取得して追加します。 しかし、insert メソッドで追加する値が指定されていた場合はそちらを使用します。

DB や MDB2 のシーケンス生成機能に直接アクセスするには DB_Table::nextID() メソッドを使用します。 このメソッドは単なるラッパーで、内部では DB あるいは MDB2 の対応するメソッドをコールしています。 次の例では、nextID() を使用して自動インクリメントの値を生成し、 その値を追加するようにしています。

例 39-8nextID() によるシーケンスへのアクセス <?php // [省略] $GuestBook オブジェクトを作成します // このテーブルに関連付けられたシーケンスの次の ID を取得します $id = $GuestBook->nextID(); // フィールドと値を設定します $row = array( 'id' => $id, 'fname' => 'Thomas', 'lname' => 'Anderson', 'signdate' => '2003-10-12', 'email' => 'neo@matrix.net' ); // テーブルに追加して、結果を表示します $result = $GuestBook->insert($row); if (PEAR::isError($result)) { // ... エラー処理コード ... } ?>

'id' カラムは自動インクリメントとして宣言されているので、 このコードと先ほどの例のコードとはまったく同じ動作をします。

行の更新

update() メソッドは、 単一の行あるいは複数行のセットのデータを用いた更新を行います。 このメソッドのパラメータは 2 つです。最初のパラメータは連装配列で、 更新するカラム名がキー、更新する値が連装配列の値となります。 2 番目の引数は、SQL の UPDATE 文で使用する WHERE 句を表す文字列です。 ただし WHERE キーワードそのものは含めません。

たとえば、すべての行で姓を "Smith" から "Jones" に変更するには次のようにします。

<?php

// [省略] $GuestBook オブジェクトを作成します

$values = array(
    'lname' => 'Jones'
    );

// WHERE 句を設定します
$where = "lname = 'Smith'";

// 更新を試みます
$result = $GuestBook->update($values, $where);
if (PEAR::isError($result)) {
    // ... エラー処理コード ...
}

?>

insert の場合と同様、カラムの宣言の際に指定した型と違う型の値で更新しようとすると update は失敗します。この場合は PEAR Error を返します。

行の削除

delete() メソッドは、 条件を満たす行あるいは行のセットを削除します。 唯一のパラメータは、削除する行を表す WHERE 条件の文字列です。 ただし WHERE キーワード自体はのぞきます。

たとえば、昨日以前に入力された行をすべて削除するには次のようにします。

<?php

// [省略] $GuestBook オブジェクトを作成します

// WHERE 句
$today = date('Y-m-d'); // formatted as yyyy-mm-dd
$where = "signdate < '$today'";

// 更新を試み、結果を表示します
$result = $GuestBook->delete($where);
if (PEAR::isError($result)) {
    // ... エラー処理コード ...
}

?>

クエリ配列

SQL の select 文は "クエリ配列" として定義されます。 クエリ配列で使用できる要素のキーのほとんどは、 SELECT 文の句に使用するキーワードを小文字にしたものとなります (たとえば 'select'、'from'、'where' など)。 また、それに対応する値はその句の残りの部分 (キーワード以外の部分) となります。クエリ配列のキーに使用できる SELECT コマンドの句は次のとおりです。

• 'select' - SELECT 句 (デフォルトは '*')

• 'from' - 取得するテーブル (デフォルトはこのテーブルの名前、つまり $this->table)

• 'join' - FROM 句に追加する join 句

• 'where' - WHERE 句

• 'group' - GROUP BY 句

• 'having' - HAVING 句

• 'order' - ORDER BY 句

'select'、'from'、'where'、'group'、'having' そして 'order' の各要素の値は、SQL 文のそれぞれの句に対応する文字列となります。 ただし、それぞれのキーワード SELECT、FROM、WHERE、GROUP BY、HAVING そして ORDER はのぞきます。もし 'join' 要素が存在した場合、 その値を単純に 'FROM' 要素の後に続けます。つまり、ここでは 'JOIN'、'INNER JOIN' あるいは 'LEFT JOIN' といったキーワードも含める必要があります。

クエリ配列で使用できるその他のキーは、select() メソッドからの返り値をどのような形式にするかを指定するものです。 たとえば以下のようなものがあります。

• 'get' - select() メソッドが結果を返す方法を指定します。 使用できる値は以下の一覧を参照ください (デフォルトは 'all')。

• 'fetchmode' - 'get' が 'all'、あるいは未設定の場合に select() が結果セットの行をどのように返すかを設定します。

• 'fetchmode_object_class' - 行をオブジェクトとして返す場合に、 行をカプセル化する際に使用するオブジェクトのクラス名を指定します。

• 'all' - 結果セットのすべての行を、行の配列として返します (これはデフォルトの設定です)。個々の行は、 カラム名をキーとする連想配列 (デフォルト) あるいは数値添字配列のいずれかとなります。

• 'assoc' - 結果を連想配列で返します。結果セットの最初のカラムが連想配列のキー、 2 番目のカラムが連想配列の値となります。

• 'col' - 最初のカラムのみを数値添字配列で返します。

• 'row' - 最初の行のみを連想配列で返します。カラム名が連想配列のキー、 そしてカラムの値が連想配列の値となります。

• 'one' - 最初の行の最初のカラムの値のみを返します。

'get' 要素を 'all' とすると (デフォルトでこのようになります)、 DB_Table::select() メソッドが返す配列の各行は カラム名をキーとする連想配列か数値添字配列、 あるいはカラム名をプロパティに対応させたオブジェクトのいずれかとなります。 返される行のデータ構造を決めるのは、クエリの 'fetchmode' 要素です。もしこれが設定されていない場合は、 DB_Table オブジェクトの $fetchmode プロパティを使用します。同様に、行をオブジェクトとして返す場合に そのオブジェクトのクラス名を決めるのはクエリの 'fetchmode_object_class' 要素です。これが設定されていない場合は DB_Table オブジェクトの $fetchmode_object_class プロパティを使用します。

クエリの 'fetchmode' 要素や 'fetchmode_object_class' 要素、 あるいは DB_Table のプロパティ $fetchmode や $fetchmode_object_class を使用すると、 内部で使用している DB や MDB2 オブジェクトの 'fetchmode' プロパティや 'fetchmode_object_class' プロパティ (DB) あるいは 'fetchmode' オプションや 'fetchmode_object_class' オプション (MDB2) を一時的にリセットすることができます。 指定する値は、それぞれ DB_FETCHMODE_* 定数や MDB2_FETCHMODE_* 定数の値でなければなりません。 もともと DB/MDB2 オブジェクトのプロパティやオプションに設定されていた値は、 select() メソッドが値を返す前に復元されます。

クエリの保存: $sql プロパティ配列

よく使われるクエリや、より複雑なクエリを作成する際の元となる "ベースライン" クエリなどは、パブリックプロパティ配列 $sql に格納しておくとよいでしょう。$sql プロパティは連想配列で、 クエリの名前が連想配列のキー、クエリの配列が連想配列の値となります。 保存されたクエリを実行するには、そのクエリに対応するキーの名前を select*() メソッドの引数として指定します。

$sql プロパティは DB_Table_Base クラスから継承したものです。したがって、クエリを DB_Table の $sql プロパティに保存して特定のテーブルへのインターフェイスとすることもできますし、 DB_Table_Database オブジェクトの $sql プロパティに保存してデータベース全体で使用することもできます。 ひとつのテーブルしか使用しないアプリケーションやクエリでは、 DB_Table オブジェクトの $sql プロパティを上の例のように使うと便利です。そのオブジェクトの select*() メソッドで、名前を指定してクエリを実行することができます。 しかし、より複雑なアプリケーションやクエリなどでは、すべてのクエリを DB_Table_Database オブジェクトの $sql プロパティに格納するほうが便利です。そして、このオブジェクトの select*() メソッドでクエリを発行するようにします。

<?php

class GuestBook_Table extends DB_Table
{
 
    // [省略] var $col = array( ... );
    // [省略] var $idx = array( ... );
         
    var $sql = array( 
    
        // 一覧用の複数の行
        'list' => array( 
            'select' => "id, signdate, CONCAT(fname, ' ', lname) AS fullname", 
            'order'  => 'signdate DESC'
        ), 

        // アイテムの詳細を表す単一の行
        'item' => array( 
            'select' => 'id, fname, lname, email, signdate', 
            'get' => 'row'
        ),

        // メールアドレス => フルネーム (一意な組み合わせのみ) 
        'emails' => array( 
            'select' => "DISTINCT email, CONCAT(fname, ' ', lname) AS fullname", 
            'order' => 'lname, fname', 
            'get' => 'assoc'
        )           
    );

}

?>

クエリの発行: select*() メソッド

select() メソッドは、 クエリを発行してその結果セットを配列で返します。 selectResult() メソッドは、 結果を DB_Result/MDB2_Result_Common オブジェクトで返します。 selectCount() メソッドは、 クエリが返す結果の行数を整数値で返します。 実際の結果セットは返しません。

これらのメソッドのインターフェイスは、どれも同じです。 まず最初のパラメータは必須で、ここにはクエリ配列かあるいは $sql プロパティ配列のキーを指定します。キーを指定した場合は、 それに対応するクエリ配列を使用するようになります。 残りのパラメータはすべてオプションで、 クエリをデータベースに発行する前に手を加えるためのものです。 2 番目のパラメータ $filter は、SQL の論理式を含む文字列で、 SELECT コマンドの WHERE 句に AND で連結されます。 3 番目のパラメータ $order を指定した場合は、 それを用いて 'ORDER BY' 句を作成します。この場合、クエリの 'order' 要素の内容は無視されます。 4 番目と 5 番目のパラメータである $start と $count には整数値を指定し、結果セットから返す最初の行の位置と最大の行数を指定します。

<?php

// [省略] DB/MDB2 オブジェクトを作成してデータベースに接続します
// [省略] GuestBook_Table のオブジェクト $GuestBook を作成します

// 保存されているクエリ 'list' を発行します。これは行の配列を返します
$rows = $GuestBook->select('list');

// 結果セットを表示します
print_r($rows);

?>

次の例は、保存されているクエリを filter、 order、start および count パラメータで修正するものです。

<?php

$filter = "signdate = '2003-08-14'";
$order = 'lname, fname';
$start = 7;
$count = 12;

// 結果を行の配列で返します
$rows = $GuestBook->select($view, $filter, $order, $start, $count);
print_r($rows);

// 結果を DB_Result/MDB2_Result_Common オブジェクトで返します
$result = $GuestBook->selectResult($view, $filter, $order, $start, $count);
print_r($result);

?>

select() で結果の行を連想配列で返すようにするには、 クエリ配列の 'fetchmode' 要素か DB_Table オブジェクトの $fetchmode プロパティを変更して DB_FETCHMODE_ASSOC か MDB2_FETCHMODE_ASSOC の適切なほうを指定しなければなりません。

<?php

// [省略] GuestBook_Table のオブジェクト $GuestBook を作成します

// フェッチモードを "associative" とします
$GuestBook->fetchmode = DB_FETCHMODE_ASSOC;

// これで、DB_Table::select() が返す配列のすべての行は
// 連想配列となり、カラム名が連想配列のキーとなります
?>

select() で、 カラム名に対応するプロパティを持つオブジェクトで結果の行を返すようにするには、 クエリ配列の 'fetchmode' 要素か DB_Table オブジェクトの $fetchmode プロパティを変更して DB_FETCHMODE_OBJECT か MDB2_FETCHMODE_OBJECT の適切なほうを指定しなければなりません。 ユーザ定義のクラスが指定されなかった場合は、 次の例のようにすべての行が stdClass のインスタンスとして返されます。

<?php

// [省略] GuestBook_Table のオブジェクト $GuestBook を作成します

// フェッチモードを DB あるいは MDB2 の "object" とします
$GuestBook->fetchmode = DB_FETCHMODE_OBJECT;

// これで、結果の配列の各行は stdClass のオブジェクトとなり、
// カラム名に対応するプロパティを保持するようになります

// すべてのカラム配列は、カラム名を配列のキーとして保持します
?>

結果セットの行をカプセル化するクラスを指定するには、クエリ配列の 'fetchmode_object_class' 要素あるいは $fetchmode_object_class プロパティでクラス名を指定します。

<?php

// [省略] GuestBook_Table のオブジェクト $GuestBook を作成します

// フェッチモードを "object" とします
$GuestBook->fetchmode = DB_FETCHMODE_OBJECT;

// 取得した行のクラスを "myRowClass" とします ...
// もちろん、この前に "myRowClass" の定義を含むファイルを
// インクルードしておく必要があります
$GuestBook->fetchmode_object_class = 'myRowClass';

// これで、結果の配列の各行は myRowClass のオブジェクトとなり、
// カラム名に対応するプロパティを保持するようになります

?>