cvs: peardoc /ja/package/database/db-table intro-generator.xml intro-table.xml

http://cvs.php.net/viewvc.cgi/peardoc/ja/package/database/db-table/intro-table.xml?view=markup&rev=1.1
Index: peardoc/ja/package/database/db-table/intro-table.xml
+++ peardoc/ja/package/database/db-table/intro-table.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<!-- EN-Revision: 1.3 Maintainer: takagi Status: ready -->

<refentry id="package.database.db-table.intro-table">
 <refnamediv>
  <refname><classname>DB_Table</classname> クラスのチュートリアル</refname>
  <refpurpose>
  単一のテーブルへのインターフェイス
  </refpurpose>
 </refnamediv>

<refsect1 id="package.database.db-table.intro-table.desc">
&title.desc;

<para>
このチュートリアルでは、<classname>DB_Table</classname>
クラスを単一のデータベーステーブルへのインターフェイスとして使用する方法を説明します。
このクラスの機能には、次のようなものがあります。
<itemizedlist>
  <listitem>
    <simpara>
    カラム定義やインデックス定義の情報の、オブジェクトのプロパティへの埋め込み
    (可搬性の高いデータ型を使用)。
    </simpara>
  </listitem>
  <listitem>
    <simpara>
    スキーマからのテーブルの作成や検証。
    </simpara>
  </listitem>
  <listitem>
    <simpara>
    SELECT、INSERT、UPDATE、そして DELETE コマンドに対応したシンプルな API。
    </simpara>
  </listitem>
  <listitem>
    <simpara>
    SELECT コマンドでの配列構文、そしてストアドクエリ。
    </simpara>
  </listitem>
  <listitem>
    <simpara>
    カラムの値の追加・更新の際のデータ型の検証。
    </simpara>
  </listitem>
  <listitem>
    <simpara>
    自動インクリメント機能のエミュレート。
    </simpara>
  </listitem>
  <listitem>
    <simpara>
    カラムの定義にもとづいた、
    <classname>HTML_QuickForm</classname> 要素の自動作成。
    </simpara>
  </listitem>
</itemizedlist>
</para>

<para>
このクラスのチュートリアルは 2 ページで構成されています。
このページでは、<classname>DB_Table</classname> の全機能のうち
<classname>HTML_QuickForm</classname> のフォーム生成機能以外を取り扱います。
フォーム生成機能については次のページで取り上げます。
このチュートリアルは、もともと別のサイトで公開されていた
<classname>DB_Table</classname> のドキュメントをもとにしています。
このドキュメントの作者は Paul M. Jones で、今でも
<ulink url="http://wiki.ciaweb.net/yawiki/index.php?area=DB_Table">
ここ</ulink> で見ることができます。元のドキュメントには
<classname>DB_Table</classname> のサブクラスの定義をカスタマイズするサンプルも含まれていますが、
それはここでは扱いません。
</para>

<para>
<classname>DB_Table</classname> クラスおよび
<classname>DB_Table_Database</classname> クラスは、どちらも抽象クラス
<classname>DB_Table_Base</classname> を継承しています。
<classname>DB_Table_Base</classname> から継承したメソッドやプロパティについては
<classname>DB_Table</classname> あるいは
<classname>DB_Table_Database</classname> オブジェクトで同じように使えます。
これらの共有メソッドやプロパティは、それぞれのマニュアルページで取り上げます。
</para>

<itemizedlist>
  <title>目次</title>
  <listitem>
     <simpara>
       <link linkend="package.database.db-table.intro-table.extend">
       <classname>DB_Table</classname> の拡張</link>
     </simpara>
     <itemizedlist>
       <listitem>
          <simpara>
          <link linkend="package.database.db-table.intro-table.extend.columns">
          カラムの定義</link>
          </simpara>
       </listitem>
       <listitem>
          <simpara>
          <link linkend="package.database.db-table.intro-table.extend.indices">
          インデックスの定義</link>
          </simpara>
       </listitem>
       <listitem>
          <simpara>
          <link linkend="package.database.db-table.intro-table.extend.autoinc">
          自動インクリメントのカラムの宣言</link>
          </simpara>
       </listitem>
     </itemizedlist>
  </listitem>
  <listitem>
     <simpara>
       <link linkend="package.database.db-table.intro-table.constructor">
       <classname>DB_Table</classname> のコンストラクタ</link>
     </simpara>
  </listitem>
  <listitem>
     <simpara>
       <link linkend="package.database.db-table.intro-table.modify">
       データの変更: 追加、更新そして削除</link>
     </simpara>
     <itemizedlist>
       <listitem>
          <simpara>
          <link linkend="package.database.db-table.intro-table.modify.insert">
          <function>insert</function> - 行の追加</link> 
          </simpara>
       </listitem>
       <listitem>
          <simpara>
          <link linkend="package.database.db-table.intro-table.modify.autoinc">
          自動インクリメントおよびシーケンス</link>
          </simpara>
       </listitem>
       <listitem>
          <simpara>
          <link linkend="package.database.db-table.intro-table.modify.update">
          <function>update</function> - 行の更新</link> 
          </simpara>
       </listitem>
       <listitem>
          <simpara>
          <link linkend="package.database.db-table.intro-table.modify.delete">
          <function>delete</function> - 行の削除</link>
          </simpara>
       </listitem>
     </itemizedlist>
  </listitem>
  <listitem>
     <simpara>
       <link linkend="package.database.db-table.intro-table.select">
       データの取得</link>
     </simpara>
     <itemizedlist>
        <listitem>
           <simpara>
           <link linkend="package.database.db-table.intro-table.select.queryarray">
           クエリ配列</link>
           </simpara>
        </listitem>
        <listitem>
           <simpara>
           <link linkend="package.database.db-table.intro-table.select.stored">
           クエリの保存: $this->sql</link>
           </simpara>
        </listitem>
        <listitem>
           <simpara>
           <link linkend="package.database.db-table.intro-table.select.submit">
           クエリの発行: <function>select*</function> メソッド</link>
           </simpara>
        </listitem>
     </itemizedlist>
  </listitem>
  <listitem>
     <simpara>
        <link linkend="package.database.db-table.intro-table.validate">
        データ型の検証</link> 
     </simpara>
  </listitem>
  <listitem>
     <simpara>
        <link linkend="package.database.db-table.intro-table.misc">
        さまざまなユーティリティメソッド</link> 
     </simpara>
     <itemizedlist>
        <listitem>
           <simpara>
           <link linkend="package.database.db-table.intro-table.misc.quote">
           <function>quote</function></link>
           </simpara>
        </listitem>
        <listitem>
           <simpara>
           <link linkend="package.database.db-table.intro-table.misc.recast">
           <function>recast</function></link>
           </simpara>
        </listitem>
        <listitem>
           <simpara>
           <link linkend="package.database.db-table.intro-table.misc.getblankrow">
           <function>getBlankRow</function></link>
           </simpara>
        </listitem>
     </itemizedlist>
  </listitem>
</itemizedlist>

</refsect1>

<refsect1 id="package.database.db-table.intro-table.extend">
<title><classname>DB_Table</classname> の拡張</title>
<para>
通常は、<classname>DB_Table</classname> のインスタンスを直接作成することはありません。
データベース内の各テーブルに対して <classname>DB_Table</classname>
のサブクラスを作成し、そのサブクラスのインスタンスを作成することになります。
テーブルのスキーマは、このオブジェクトのプロパティとして埋め込まれています。
カラムの定義は $col プロパティの配列に格納されており、インデックスは
$idx プロパティの配列に格納されています。
通常は、これらのプロパティ配列はサブクラスの定義の中で行います。
これが、テーブルのスキーマ情報を記録する場所となります。
</para>

<para>
このようなデータベースゲートウェイ、つまり RDBMS
の各テーブルにクラスを関連付ける方式の利点のひとつは、
各テーブルに固有のプロパティやふるまいを適切な箇所で定義できるということです。
独自の挙動や検証機能などを作成するには、
既存のクラスメソッドをオーバーライドするか、あるいは新たなメソッドを作成します。
<classname>DB_Table</classname> には、一般的に使われる
SELECT クエリ用に用いる $sql プロパティ配列もあります。
</para>

<para>
このパッケージは、RDBMS 上のテーブルとそれに対応する
<classname>DB_Table</classname> サブクラスのどちらか一方があれば、
もう一方を自動的に作成することができます。
同じような内容を何度も書く必要はありません。
<itemizedlist>
<listitem>
<simpara>
プログラム上でのテーブルの作成:
各テーブルに対応する <classname>DB_Table</classname> のサブクラスの定義を作成し、
そのサブクラスのインスタンスを使用してデータベース上に実際のテーブルを作成します。
</simpara>
</listitem>
<listitem>
<simpara>
リフレクションおよびコード生成:
<classname>DB_Table_Generator</classname> クラスを使い、既存のデータベースから
<classname>DB_Table</classname> のサブクラスの定義の雛形を作成します。
この雛形には、テーブル定義のほかに関連するコードも含まれています。
</simpara>
</listitem>
</itemizedlist>
このチュートリアルでは最初の方法を使用します。
つまり、サブクラスの定義は自分で書くことになります。
もう一方の方式についての説明は
<classname>DB_Table_Generator</classname> クラスのチュートリアルで行います。
</para>

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

<para>
例として、GuestBook テーブルを作成することを考えてみましょう。
このテーブルには、訪問者の姓と名、メールアドレス、
そして書き込み日時を記録するものとします。さらに、
各行に一意な ID を与える必要があります。
このテーブルのカラムは次のようになるでしょう。
<itemizedlist>
   <listitem>
      <simpara>
      id -- 各行で一意な整数値 (必須。つまり null は許可しない)。
      </simpara>
   </listitem>
   <listitem>
      <simpara>
      fname -- 最大 32 文字までの文字列。訪問者の名前。
      </simpara>
   </listitem>
   <listitem>
      <simpara>
      lname -- 最大 64 文字までの文字列。訪問者の姓。
      </simpara>
   </listitem>
   <listitem>
      <simpara>
      email -- 最大 255 文字までの文字列。訪問者のメールアドレス
      (必須。つまり null は許可しない)。
      </simpara>
   </listitem>
   <listitem>
      <simpara>
      signdate -- 訪問者が書き込んだ日付
      (必須。つまり null は許可しない)。
      </simpara>
   </listitem>
 </itemizedlist>
 </para>

<para>
これらのカラム定義はプロパティ配列 $col で行う必要があります。
以下に、<classname>GuestBook_Table</classname> という名前の
<classname>DB_Table</classname> サブクラスにおける
$col の宣言の例を示します。これが、データベースの
GuestBook テーブルに対応するものとなります。
<example>
<title>GuestBook のカラム定義</title>
<programlisting role="php">
<![CDATA[
<?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)
     );
?>
]]>
</programlisting>
</example>
</para>
</refsect2> 

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

<para>
今回の例の GuestBook では、単一カラムのインデックスをふたつ作成します。まず最初は
"id" カラムに対する主キーインデックスです。もうひとつは、"signdate"
カラムに通常のインデックスを作成します。訪問者を日付や時刻で検索することがあると想定されるからです。
この場合の $idx プロパティの宣言は以下のようになります。
<example>
<title>GuestBook のインデックス定義</title>
<programlisting role="php">
<![CDATA[
<?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'
        )
    ); 
} 
?>
]]>
</programlisting>
</example>
</para>

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

<para>
複数カラムのインデックスの例として、fname と lname カラムに対するインデックス
"namefl" を定義してみます。
<example>
<title>複数カラムのインデックスの定義</title>
<programlisting role="php">
<![CDATA[
<?php

class GuestBook_Table extends DB_Table
{
    // カラムの定義
    // var $col = array( ... )

    // インデックスの定義
    var $idx = array(

            // さきほどの単一カラムのインデックスに加え、

            'namefl' = array(
                'type' => 'normal',
                'cols' => array('fname', 'lname')
            )
        );
}
?>
]]>
</programlisting>
</example>
</para>

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

class GuestBook_Table extends DB_Table
{
    
    // カラムの定義
    // var $col = array(...);
       
    // インデックスの定義
    var $idx = array( 
   
        // 主キーインデックス 'id' を、'id' カラムに定義します
        'id' => 'primary',
        
        // 通常のインデックス 'signdate' を、'signdate' カラムに定義します
        'signdate' => 'normal'

    ); 
} 
?>
]]>
</programlisting>
</example>
</para>

</refsect2> 
<refsect2 id="package.database.db-table.intro-table.extend.autoinc">
<title>自動インクリメントのカラムの宣言</title>
<para>
各テーブルについてひとつの整数型カラムを、
自動インクリメントのカラムとして宣言することができます。
このカラムは、通常は主キーとなります。この宣言をすることによって変化するのは、
<function>insert</function> メソッドの振る舞いだけです。
<function>insert</function> メソッドを実行する際に
自動インクリメントのカラムを省略したり NULL を渡したりすると、
自動生成された整数値が挿入されます。
</para>

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

<example>
<title>自動インクリメント指定</title>
<programlisting role="php">
<![CDATA[
<?php

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

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

}

?>
]]>
</programlisting>
</example>

</refsect2> 

</refsect1>

<refsect1 id="package.database.db-table.intro-table.constructor">
<title><classname>DB_Table</classname> のコンストラクタ</title>
<para>
個々の <classname>DB_Table</classname> オブジェクトは、<classname>DB</classname> 
あるいは <classname>MDB2</classname> のデータベース接続オブジェクトをラップしています。
これらのオブジェクトは、<classname>DB_Table</classname>
のコンストラクタへの最初のパラメータとして渡します。
ひとつの <classname>DB/MDB2</classname> オブジェクトを、
複数の <classname>DB_Table</classname> オブジェクトで共用することができます。
コンストラクタの 2 番目のパラメータには、
関連付ける RDBMS のテーブル名を指定します。
オプションの 3 番目のパラメータ $create を指定すると、
コンストラクタの実行時にテーブルが存在しなければテーブルを作成します。
テーブルが存在する場合はその構造を検証します
(詳しくは後ほど説明します)。
</para>

<para>
以下の例では、GuestBook サブクラスのインスタンスを作成しています。
このクラスは GuestBook テーブルをバインドします。
$auto_create = 'safe' を指定することで、
GuestBook という名前のテーブルが存在しない場合に作成させるようにしています。
テーブルが存在する場合は何もしません。
<example>
<title>GuestBook_Table オブジェクトの作成</title>
<programlisting role="php">
<![CDATA[
<?php

// 基本クラス群を読み込みます
require_once 'MDB2.php';
require_once 'DB/Table.php';
require_once 'Guestboook_Table.php';

// PEAR MDB2 (あるいは DB) オブジェクトを作成します
$dsn = "phptype://username:password@localhost/database";
$conn = MDB2::connect($dsn);

// GuestBook を準備して作成します
$table  = 'GuestBook';
$create = 'safe';
$GuestBook =& new GuestBook_Table($conn, $table, $create);

// 結果を表示します
if ($GuestBook->error) {
     echo "失敗しました!  もう一度ためしてみましょう。";
     print_r($GuestBook->error);
} else {
     echo "成功しました!";
     print_r($GuestBook);
}

?>
]]>
</programlisting>
</example>
接続オブジェクト $conn は <classname>DB</classname> あるいは
<classname>MDB2</classname> オブジェクトであり、参照で渡します。
</para>

<para>
$create に指定できる値は以下のとおりです。
<itemizedlist>
   <listitem>
      <simpara>
      false を指定すると、作成しません (デフォルト)。
      </simpara>
   </listitem>
   <listitem>
      <simpara>
      'drop' を指定すると、
      同名のテーブルが存在する場合はそれを削除してから改めて作成します。
      </simpara>
   </listitem>
   <listitem>
      <simpara>
      'safe' を指定すると、
      テーブルが存在しない場合は作成します。
      存在する場合は何もしません。
      </simpara>
   </listitem>
   <listitem>
      <simpara>
      'verify' を指定すると、
      テーブルが存在するかどうかを調べ、そのスキーマを検証します。
      検証する内容は、すべてのカラムが存在するかどうか、
      すべてのカラムの型が正しいものか、
      そしてすべてのインデックスが存在して正しい型であるかどうかです。
      </simpara>
   </listitem>
   <listitem>
      <simpara>
      'alter' は、テーブルが存在しない場合の挙動は 'safe' と同じです。
      テーブルが存在する場合はスキーマの検証を行い、
      必要に応じてスキーマを変更します。
      </simpara>
   </listitem>
</itemizedlist>
</para>
</refsect1>

<refsect1 id="package.database.db-table.intro-table.modify">
<title>データの変更: 追加、更新そして削除</title>

<para>
<classname>DB_Table</classname> のメソッド <function>insert</function>、
<function>update</function> および <function>delete</function>
は、データの行を追加したり更新したり削除したりするための便利なインターフェイスです。
行を追加したり更新したりする場合は、insert メソッドや update
メソッドに連想配列を渡します。この配列のキーがカラム名となります。
</para>

<refsect2 id="package.database.db-table.intro-table.modify.insert">
<title>行の追加</title>
<para>
GuestBook テーブルに行を追加するには、
<function>insert</function> メソッドを使用します。
このメソッドに渡すパラメータは連想配列で、
そのキーがカラム名、そして追加する値をキーに関連づけます。
<example>
<title>行の追加</title>
<programlisting role="php">
<![CDATA[
<?php

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

// フィールドとその値を関連づけます
$row = array(
    'fname'    => 'Thomas',
    'lname'    => 'Anderson',
    'signdate' => '2003-10-12',
    'email'    => '[email protected]'
);

// テーブルに追加し、結果を表示します
$result = $GuestBook->insert($row);
if (PEAR::isError($result)) {
    // エラー処理コード
}

?>
]]>
</programlisting>
</example>
</para>

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

<refsect2 id="package.database.db-table.intro-table.modify.autoinc">
<title>自動インクリメントカラムおよびシーケンス</title>
<para>
<classname>DB_Table</classname> は、
<classname>DB</classname> あるいは <classname>MDB2</classname>
が作成したシーケンスを使用して自動インクリメントの整数型の ID
を生成することができます。insert メソッドで
自動インクリメント型のカラムの値が設定されていなかったり
PHP の NULL が設定されていたりした場合は、
自動インクリメントのシーケンスの値を使用してそのカラムにデータを追加します。
上の例では、'id' カラムに対して、
シーケンスの値を取得して追加します。
しかし、insert メソッドで追加する値が指定されていた場合はそちらを使用します。
</para>

<para>
<classname>DB</classname> や
<classname>MDB2</classname> のシーケンス生成機能に直接アクセスするには
<function>DB_Table::nextID</function> メソッドを使用します。
このメソッドは単なるラッパーで、内部では <classname>DB</classname>
あるいは <classname>MDB2</classname> の対応するメソッドをコールしています。
次の例では、<function>nextID</function>
を使用して自動インクリメントの値を生成し、
その値を追加するようにしています。
<example>
<title>nextID() によるシーケンスへのアクセス</title>
<programlisting role="php">
<![CDATA[
<?php

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

// このテーブルに関連付けられたシーケンスの次の ID を取得します
$id = $GuestBook->nextID();

// フィールドと値を設定します
$row = array(
    'id'       => $id,
    'fname'    => 'Thomas',
    'lname'    => 'Anderson',
    'signdate' => '2003-10-12',
    'email'    => '[email protected]'
);

// テーブルに追加して、結果を表示します
$result = $GuestBook->insert($row);
if (PEAR::isError($result)) {
    // ... エラー処理コード ...
}

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

<refsect2 id="package.database.db-table.intro-table.modify.update">
<title>行の更新</title>
<para>
<function>update</function> メソッドは、
単一の行あるいは複数行のセットのデータを用いた更新を行います。
このメソッドのパラメータは 2 つです。最初のパラメータは連装配列で、
更新するカラム名がキー、更新する値が連装配列の値となります。
2 番目の引数は、SQL の UPDATE 文で使用する WHERE 句を表す文字列です。
ただし WHERE キーワードそのものは含めません。
</para>

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

<example>
<title>行のセットの更新</title>
<programlisting role="php">
<![CDATA[
<?php

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

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

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

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

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

<refsect2 id="package.database.db-table.intro-table.modify.delete">
<title>行の削除</title>
<para>
<function>delete</function> メソッドは、
条件を満たす行あるいは行のセットを削除します。
唯一のパラメータは、削除する行を表す WHERE 条件の文字列です。
ただし WHERE キーワード自体はのぞきます。
</para>

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

<example>
<title>行のセットの削除</title>
<programlisting role="php">
<![CDATA[
<?php

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

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

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

?>
]]>
</programlisting>
</example>

</refsect2>

</refsect1>

<refsect1 id="package.database.db-table.intro-table.select">
<title>データの取得</title>
<para>
<classname>DB_Table</classname> は、配列形式を使用して SQL の
SELECT 文を構築します。SELECT 文の各句 (たとえば SELECT、
FROM、WHERE 句など) がそれぞれ個別の要素となります。
これにより、クエリの変更が簡単にできるようになります。
たとえば返される結果の行数を制限するために WHERE 句を追加するといったことも簡単です。
クエリの内容を表す配列は、プロパティ配列 $sql
に格納されるようになります。
</para>

<para>
クエリをデータベースに送信する方法は二通りあります。
<function>select</function> メソッドは結果セットを配列で返し、
<function>selectResult</function> メソッドは結果セットを
<classname>DB_Result</classname> あるいは
<classname>MDB2_Result_Common</classname> のオブジェクトで返します。
これらのメソッドはすべて <classname>DB_Table_Base</classname>
基底クラスから継承したものであり、<classname>DB_Table_Database</classname>
オブジェクトのメソッドとしても使用可能です。
</para>

<refsect2 id="package.database.db-table.intro-table.select.queryarray">
<title>クエリ配列</title>
<para>
SQL の select 文は "クエリ配列" として定義されます。
クエリ配列で使用できる要素のキーのほとんどは、
SELECT 文の句に使用するキーワードを小文字にしたものとなります
(たとえば 'select'、'from'、'where' など)。
また、それに対応する値はその句の残りの部分 (キーワード以外の部分)
となります。クエリ配列のキーに使用できる SELECT コマンドの句は次のとおりです。
</para>
<itemizedlist>
<listitem>
<simpara>
'select' - SELECT 句
           (デフォルトは '*')
</simpara>
</listitem>
<listitem>
<simpara>
'from' - 取得するテーブル
         (デフォルトはこのテーブルの名前、つまり $this->table)
</simpara>
</listitem>
<listitem>
<simpara>
'join' - FROM 句に追加する join 句
</simpara>
</listitem>
<listitem>
<simpara>
'where' - WHERE 句
</simpara>
</listitem>
<listitem>
<simpara>
'group' - GROUP BY 句
</simpara>
</listitem>
<listitem>
<simpara>
'having' - HAVING 句
</simpara>
</listitem>
<listitem>
<simpara>
'order' - ORDER BY 句
</simpara>
</listitem>
</itemizedlist>
<para>
'select'、'from'、'where'、'group'、'having' そして 'order'
の各要素の値は、SQL 文のそれぞれの句に対応する文字列となります。
ただし、それぞれのキーワード SELECT、FROM、WHERE、GROUP BY、HAVING
そして ORDER はのぞきます。もし 'join' 要素が存在した場合、
その値を単純に 'FROM' 要素の後に続けます。つまり、ここでは
'JOIN'、'INNER JOIN' あるいは 'LEFT JOIN'
といったキーワードも含める必要があります。
</para>

<para>
クエリ配列で使用できるその他のキーは、<function>select</function>
メソッドからの返り値をどのような形式にするかを指定するものです。
たとえば以下のようなものがあります。
<itemizedlist>
 <listitem>
  <simpara>
   'get' - <function>select</function> メソッドが結果を返す方法を指定します。
           使用できる値は以下の一覧を参照ください
           (デフォルトは 'all')。
  </simpara>
 </listitem>
 <listitem>
  <simpara>
   'fetchmode' - 'get' が 'all'、あるいは未設定の場合に
          <function>select</function> が結果セットの行をどのように返すかを設定します。 
  </simpara>
 </listitem>
 <listitem>
  <simpara>
  'fetchmode_object_class' - 行をオブジェクトとして返す場合に、
         行をカプセル化する際に使用するオブジェクトのクラス名を指定します。
  </simpara>
 </listitem>
</itemizedlist>
これらの 3 つの要素が影響するのは
<function>select</function> メソッドだけであり、
<function>selectResult</function> メソッドの結果には何の影響も及ぼしません。
'get' 要素で使用できる値は次のとおりです。
<itemizedlist>
<listitem>
<simpara>
'all' - 結果セットのすべての行を、行の配列として返します
(これはデフォルトの設定です)。個々の行は、
カラム名をキーとする連想配列 (デフォルト)
あるいは数値添字配列のいずれかとなります。
</simpara>
</listitem>
<listitem>
<simpara>
'assoc' - 結果を連想配列で返します。結果セットの最初のカラムが連想配列のキー、
2 番目のカラムが連想配列の値となります。
</simpara>
</listitem>
<listitem>
<simpara>
'col' - 最初のカラムのみを数値添字配列で返します。
</simpara>
</listitem>
<listitem>
<simpara>
'row' - 最初の行のみを連想配列で返します。カラム名が連想配列のキー、
そしてカラムの値が連想配列の値となります。
</simpara>
</listitem>
<listitem>
<simpara>
'one' - 最初の行の最初のカラムの値のみを返します。
</simpara>
</listitem>
</itemizedlist>
'get' 要素に使用できる値は、それぞれ
<classname>DB</classname> および <classname>MDB2</classname> の
get* メソッドの名前と対応します。これらのメソッドが、
<function>DB_Table::select</function> の内部でコールされます。つまり、
'get' 要素の値が 'all' の場合はクエリを発行する際に
<function>DB/MDB2::getAll</function> メソッドをコールするということです。
この際に、クエリ配列の内容をもとにして SQL クエリを作成します。そして
<function>DB_Table::select</function> は
<function>getAll</function> の返り値をそのまま返します。同様に 'get'
要素の値が 'assoc' の場合は <function>getAssoc</function>、
'col' の場合は <function>getCol</function>、
'one' の場合は <function>getOne</function>、そして
'row' の場合は <function>getRow</function> をコールします。
</para>

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

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

</refsect2>

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

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

<example>
<title><classname>DB_Table</classname> サブクラスの定義中でのベースラインクエリの定義</title>
<para>
GuestBook テーブルで使用する 3 種類の SELECT 文を定義して保存しましょう。
これらを元にして、より複雑なクエリを作成することにします。
<itemizedlist>
<listitem>
<simpara>
guestbook の行を新しい順に返し、フルネームと投稿日時を表示するもの
</simpara>
</listitem>
<listitem>
<simpara>
guestbook の単一の行のすべてのフィールドを返すもの
</simpara>
</listitem>
<listitem>
<simpara>
メールアドレスとフルネームの一意な組み合わせの一覧を、
姓と名の順で返すもの
</simpara>
</listitem>
</itemizedlist>
以下のプログラムでは、これらのクエリを
GuestBook_Table クラス定義中の $sql プロパティの要素として宣言しています。
</para>

<programlisting role="php">
<![CDATA[
<?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'
        )           
    );

}

?>
]]>
</programlisting>
</example>

</refsect2>

<refsect2 id="package.database.db-table.intro-table.select.submit">
<title>クエリの発行: <function>select*</function> メソッド</title>
<para>
<function>select</function> メソッドは、
クエリを発行してその結果セットを配列で返します。
<function>selectResult</function> メソッドは、
結果を <classname>DB_Result/MDB2_Result_Common</classname> 
オブジェクトで返します。
<function>selectCount</function> メソッドは、
クエリが返す結果の行数を整数値で返します。
実際の結果セットは返しません。
</para>

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

<example>
<title>保存されているクエリの発行</title>
<programlisting role="php">
<![CDATA[
<?php

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

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

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

?>
]]>
</programlisting>
</example>

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

<example>
<title>Filter、Order、および Limit パラメータの使用法</title>
<programlisting role="php">
<![CDATA[
<?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);

?>
]]>
</programlisting>
</example>

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

<example>
<title>Fetchmode を指定し、結果を連想配列で返すようにする</title>
<programlisting role="php">
<![CDATA[
<?php

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

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

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

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

<example>
<title>行を stdClass のオブジェクトで返す</title>
<programlisting role="php">
<![CDATA[
<?php

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

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

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

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

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

<example>
<title>結果の行をユーザ定義クラスのオブジェクトで返す</title>
<programlisting role="php">
<![CDATA[
<?php

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

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

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

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

?>
]]>
</programlisting>
</example>
</refsect2>

</refsect1>

<refsect1 id="package.database.db-table.intro-table.validate">
<title>データ型の検証</title>

<para>
<classname>DB_Table</classname> は、自動的にデータの検証を行うことができ、
追加したり更新したりするデータが対応するカラムの型と整合性があるかどうかを調べることができます。
データ型の検証は、追加や更新の際にデフォルトで行われます。
追加や更新の際の検証を有効にしたり無効にしたりするには、それぞれ
<function>autoValidInsert</function> メソッドおよび
<function>autoValidUpdate</function> メソッドを使用します。
これらのメソッドには boolean 型のパラメータを指定し、
true の場合は検証機能が有効に、false の場合は無効にします。
</para>

<para>
追加したり更新したりするデータの型の検証を実施亜に行うのは、それぞれ
<function>validInsert</function> メソッドあるいは
<function>validUpdate</function> メソッドとなります。
これらのメソッドにはひとつのパラメータを指定します。
このパラメータに渡すのは、カラム名がキーとなる連想配列です。
検証に成功した場合は true、失敗した場合は
<classname>PEAR_Error</classname> オブジェクトを返します。
これらのメソッドは、自動検証を有効にしている場合に
<function>insert</function> メソッドや <function>update</function>
メソッドの内部から自動的にコールされます。
自動検証機能をカスタマイズするには、これらのメソッドをオーバーライドして実装します。
</para>

<para>
単一のカラムの型を検証するのが
<function>isValid</function> メソッドです。
このメソッドの最初のパラメータには、検証したい値を指定します。
そして 2 番目のパラメータには、検証したい
<classname>DB_Table</classname> データ型の名前を指定します。
このメソッドは、行の検証用の 2 つのメソッドの内部からコールされます。
</para>

</refsect1>

<refsect1 id="package.database.db-table.intro-table.misc">
<title>さまざまなユーティリティメソッド</title>
  <para>
  <table>
   <title>さまざまなメソッド</title>
   <tgroup cols="2">
     <thead>
       <row>
         <entry>メソッド</entry>
         <entry>説明</entry>
       </row> 
     </thead> 
     <tbody> 
       <row>
         <entry id="package.database.db-table.intro-table.misc.quote">
         <function>quote</function></entry>
         <entry>SQL クエリで使用するために、
         適切な方式で値のクォートとエスケープを行います。
         <function>DB::smartQuote</function> や
         <function>MDB2::quote</function> メソッドの単純なラッパーで、
         内部ではこれらのメソッドをコールしています。
         </entry>
       </row> 
       <row>
         <entry id="package.database.db-table.intro-table.misc.recast">
         <function>recast</function></entry>
         <entry>データの連想配列 (カラム名が連想配列のキー、
         カラムの値が連想配列の値) を受け取り、
         個々の値をそのカラム用の適切なフォーマットにキャストします。
         </entry>
       </row> 
       <row>
         <entry id="package.database.db-table.intro-table.misc.getblankrow">
         <function>getBlankRow</function></entry>
         <entry>カラム名をキーとし、各カラムの空の値を関連づけた連想配列を返します。
         連想配列の値は、関連づけられたいるカラムの型に応じた適切なフォーマットの値となります。</entry>
       </row> 
     </tbody> 
   </tgroup>
  </table>
  </para>

</refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

http://cvs.php.net/viewvc.cgi/peardoc/ja/package/database/db-table/intro-generator.xml?view=markup&rev=1.1
Index: peardoc/ja/package/database/db-table/intro-generator.xml
+++ peardoc/ja/package/database/db-table/intro-generator.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<!-- EN-Revision: 1.5 Maintainer: takagi Status: ready -->

<refentry id="package.database.db-table.intro-generator">

<refnamediv>
  <refname>
  <classname>DB_Table_Generator</classname> クラスのチュートリアル
  </refname>
  <refpurpose>
  既存のデータベース用のコードの生成
  </refpurpose>
</refnamediv>

<refsect1 id="package.database.db-table.intro-generator.desc">
&title.desc;
<para> 
<classname>DB_Table_Generator</classname> クラスは、DB_Table
パッケージを用いて既存のデータベースを操作するためのコードを生成するためのものです。
これは、データベース内の全テーブルに対する <classname>DB_Table</classname>
のサブクラスの雛形を作成します。テーブルのスキーマは、
データベースに問い合わせることによって取得します。
また、データベースに接続するためのコードや <classname>DB_Table_Database</classname>
オブジェクトを作成するためのコードも含めることができます。
</para>
</refsect1>

<refsect1 id="package.database.db-table.intro-generator.names">
<title>命名規約とファイル構成</title>
<para>
<classname>DB_Table_Generator</classname> オブジェクトが生成するすべてのコードは、
そのオブジェクトの $class_write_path プロパティで指定したディレクトリに書き込まれます。
デフォルトでは、これはカレントディレクトリになります。
デフォルトでは、たとえば &apos;thing&apos; テーブル用に作成するクラスの名前は
<classname>Thing_Table</classname> となります。
つまり、テーブル名の先頭を大文字にし、最後に &apos;_Table&apos;
をつけたものがクラス名になるということです。
この最後につける文字列については $class_suffix プロパティで変更することができます。
このクラス定義を含むファイルの名前は、クラス名に拡張子 php をつけたものになります。
つまり、たとえば &apos;Thing_Table.php&apos; のようになるということです。
このサブクラスから作成するインスタンスの名前は、テーブル名と同じになります。
つまり、たとえば &apos;thing&apos; のようになります。
</para> 
</refsect1>

<refsect1 id="package.database.db-table.intro-generator.generation">
<title>コード生成の手順</title>
<para>
データベース $database の全テーブル用のコードを生成するには、
まず <classname>DB</classname> あるいは
<classname>MDB2</classname> のオブジェクトを $conn
という名前で接続してデータベースに接続し、次のコードを実行します。
</para>
<example>
<title>データベース全体用のコードの生成</title>
<programlisting role="php">
<![CDATA[     
<?php
require_once 'DB/Table/Generator.php';

// [省略] ここで、DB あるいは MDB2 オブジェクトを $conn という名前で作成します

// Generator オブジェクトのインスタンスを作成します
$generator = new DB_Table_Generator($conn, $database);

// 生成したコードの保存先ディレクトリを選択します
$generator->class_write_path = '/var/www/html/app1/db_table' ;

// DB_Table のサブクラスを定義するファイルを作成します
$generator->generateTableClassFiles();

// 'Database.php' ファイルを作成します
$generator->generateDatabaseFile();

?>
]]> 
</programlisting>  
</example>

<para>
上の例では、すべてのコードが '/var/www/html/app1/db_table'
(最後のディレクトリ区切り文字は不要) に書き込まれます。
このディレクトリが存在しない場合は、(可能なら) ディレクトリを作成します。
ディレクトリがすでに存在する場合、既存のファイルの上書きは行いません。
$class_write_path が設定されていない場合
(たとえばサンプルでこの行を削除した場合) は、
すべてのコードがカレントディレクトリに書き込まれます。
</para>

<para>
<function>generateTableClassFiles</function> メソッドは、
各テーブル用のサブクラス定義の雛形を生成します。
テーブルごとに個別のファイルに書き込まれます。
上のように引数を指定せずにコールした場合は、
そのデータベース内のすべてのテーブルのサブクラス定義を生成します。
</para>

<para> 
<function>generateDatabaseFile</function> メソッドは
&apos;Database.php&apos; という名前のファイルを生成します。
デフォルトでは、ここにはデータベースへの接続用のコードや親の
<classname>DB_Table_Database</classname> オブジェクトの作成用のコードが書き込まれます。
<function>generateDatabaseFile</function> メソッドを上の例のようにコールする場合は、
<function>generateTableClassFiles</function> の後にコールしなければなりません。
&apos;Database.php&apos; ファイル内のコードでは、
("require_once" を使用して) 各テーブル用のサブクラスの定義を読み込み、
個々の <classname>DB_Table</classname> サブクラスのオブジェクトを作成
(ひとつのテーブルごとにひとつのオブジェクト) し、さらに親の
<classname>DB_Table_Database</classname> オブジェクトのインスタンスを作成し、
すべてのテーブルを親に追加し、カラム名にもとづいた外部キーリレーションを推測します。
一般に、このファイルには多少手を加える必要があります。
つまり、データソース名 (DSN) を指定したり
自動判別に失敗した外部キーリレーションを指定したりといったことです。
</para>

<para>
デフォルトでは、<function>generateTableClassFiles</function> および
<function>generateDatabaseFiles</function>
はデータベース内の全テーブル用のコードを生成します。
特定のテーブル用のコードのみを生成させるには、パブリックプロパティ
$tables にテーブル名の一覧を指定してからこれらのメソッドをコールします。
たとえば、
&apos;table1&apos;、&apos;table2&apos; および &apos;table3&apos;
の 3 テーブルについてのコードを生成するには、次のようにします。
</para>

<example>
<title>指定したテーブル用のコード生成</title>
<programlisting role="php">
<![CDATA[     
<?php
require_once 'DB/Table/Generator.php'

// [省略] ここで、DB あるいは MDB2 オブジェクトを $conn という名前で作成します

// Generator オブジェクトのインスタンスを作成します
$generator = new DB_Table_Generator($conn, $database);

// 生成したコードの保存先ディレクトリを選択します
$generator->class_write_path = '/var/www/html/app1/db_table' ;

// テーブルを指定します
$generator->tables = array('table1', 'table2', 'table3');

// DB_Table のサブクラスを定義するファイルを作成します
$generator->generateTableClassFiles();

// 'Database.php' ファイルを作成します
$generator->generateDatabaseFile();

?>
]]> 
</programlisting>  
</example>

<para>
<function>generateTableClassFiles</function> をコールした時点で
DB_Table_Generator オブジェクトのプロパティ $tables
に配列が設定されていない場合は、
<function>generateTableClassFiles</function>
メソッドはデータベースに問い合わせて全テーブルの一覧の配列を取得し
(内部で <function>getTableNames</function> メソッドをコールします)、
$table プロパティにその内容を設定します。
</para>

</refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->