repo_zf1/documentation/manual/ja/module_specs/Zend_Db_Table.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 17600 -->
<sect1 id="zend.db.table">

    <title>Zend_Db_Table</title>

    <sect2 id="zend.db.table.introduction">

        <title>導入</title>

        <para>
            <classname>Zend_Db_Table</classname> クラスは、データベースのテーブルへの
            オブジェクト指向のインターフェイスです。
            テーブルに対するさまざまな共通操作のためのメソッドを提供します。
            基底クラスは拡張可能なので、独自のロジックを組み込むこともできます。
        </para>

        <para>
            <classname>Zend_Db_Table</classname> は、
            <ulink url="http://www.martinfowler.com/eaaCatalog/tableDataGateway.html">テーブルデータゲートウェイ</ulink>
            パターンを実装したものです。また、そのほかにも
            <ulink url="http://www.martinfowler.com/eaaCatalog/rowDataGateway.html">行データゲートウェイ</ulink>
            パターンを実装したクラスも含んでいます。
        </para>

    </sect2>

    <sect2 id="zend.db.table.concrete">
        <title>Zend_Db_Table を具象クラスとして使用する方法</title>

        <para>
            Zend Framework 1.9 以降では、<classname>Zend_Db_Table</classname> のインスタンスを作成することができます。
            つまり、一つのテーブルに対して select、insert、update、delete
            などといった単純な操作を行うためだけにわざわざ基底クラスを継承して設定する必要がなくなるということです。
            以下に、もっとも単純な使用例を示します。
        </para>

        <example id="zend.db.table.defining.concrete-instantiation.example1">

            <title>文字列で名前を指定するだけのテーブルクラスの宣言</title>

                <programlisting language="php"><![CDATA[
Zend_Db_Table::setDefaultAdapter($dbAdapter);
$bugTable = new Zend_Db_Table('bug');
]]></programlisting>

        </example>

        <para>
            これが、もっとも単純な使用例です。
            以下で説明する <classname>Zend_Db_Table</classname> のオプションはまったく設定していません。
            具象クラスの使用例に加えてより複雑なリレーション機能を使いたくなったときは
            <classname>Zend_Db_Table_Definition</classname> のドキュメントを参照ください。
        </para>

    </sect2>

    <sect2 id="zend.db.table.defining">

        <title>テーブルクラスの定義</title>

        <para>
            データベース内でアクセスしたいテーブルそれぞれについて、
            <classname>Zend_Db_Table_Abstract</classname> を継承したクラスを定義します。
        </para>

        <sect3 id="zend.db.table.defining.table-schema">

            <title>テーブル名およびスキーマの定義</title>

            <para>
                そのクラスが定義しているデータベースのテーブルを定義するには、
                protected な変数 <varname>$_name</varname> を使用します。
                これは文字列で、データベースでのテーブル名を指定する必要があります。
            </para>

            <example id="zend.db.table.defining.table-schema.example1">

                <title>テーブル名を明示的に指定することによるテーブルクラスの宣言</title>

                <programlisting language="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';
}
]]></programlisting>

            </example>

            <para>
                テーブル名を指定しなかった場合のデフォルトは、クラス名となります。
                このデフォルトを使用する場合は、クラス名をデータベースでのテーブル名と一致させる必要があります。
            </para>

            <example id="zend.db.table.defining.table-schema.example">

                <title>テーブル名を暗黙的に指定することによるテーブルクラスの宣言</title>

                <programlisting language="php"><![CDATA[
class bugs extends Zend_Db_Table_Abstract
{
    // テーブル名とクラス名が一致します
}
]]></programlisting>

            </example>

            <para>
                テーブルのスキーマについても、protected 変数
                <varname>$_schema</varname> で宣言することができます。
                あるいは <varname>$_name</varname> プロパティでテーブル名の前にスキーマ名をつなげて指定することもできます。
                <varname>$_name</varname> で指定したスキーマのほうが、
                <varname>$_schema</varname> プロパティで指定したスキーマよりも優先されます。
                <acronym>RDBMS</acronym> によってはスキーマのことを「データベース」や「表領域」
                などということもありますが、同じように使用できます。
                スキーマを、テーブル名の一部として宣言することもできます。
            </para>

            <example id="zend.db.table.defining.table-schema.example3">

                <title>テーブルクラスでのスキーマの宣言</title>

                <programlisting language="php"><![CDATA[
// 一つ目の方法
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_schema = 'bug_db';
    protected $_name   = 'bugs';
}

// 二つ目の方法
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bug_db.bugs';
}

// スキーマを $_name と $_schema の両方で指定した場合は、
// $_name で指定したものが優先されます

class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name   = 'bug_db.bugs';
    protected $_schema = 'ignored';
}
]]></programlisting>

            </example>

            <para>
                スキーマ名とテーブル名は、コンストラクタの設定ディレクティブでも指定することができます。
                これは、<varname>$_name</varname> や <varname>$_schema</varname>
                といったプロパティで設定したデフォルト値を上書きします。
                <code>name</code> ディレクティブで指定したスキーマ名は、
                <code>schema</code> オプションで指定したスキーマ名より優先されます。
            </para>

            <example id="zend.db.table.defining.table-schema.example.constructor">

                <title>インスタンス作成時のテーブル名とスキーマ名の指定</title>

                <programlisting language="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
}

// 最初の方法

$tableBugs = new Bugs(array('name' => 'bugs', 'schema' => 'bug_db'));

// もうひとつの方法

$tableBugs = new Bugs(array('name' => 'bug_db.bugs'));

// スキーマを 'name' と 'schema' の両方で指定した場合は、
// 'name' で指定したものが優先されます

$tableBugs = new Bugs(array('name' => 'bug_db.bugs',
                            'schema' => 'ignored'));
]]></programlisting>

            </example>

            <para>
                スキーマ名を指定しなかった場合のデフォルトは、
                そのデータベースアダプタが接続しているスキーマとなります。
            </para>

        </sect3>

        <sect3 id="zend.db.table.defining.primary-key">

            <title>テーブルの主キーの定義</title>

            <para>
                すべてのテーブルは主キーを持たなければなりません。
                主キーカラムを宣言するには、protected 変数
                <varname>$_primary</varname> を使用します。
                これは、単一のカラムの名前を表す文字列か、
                もし主キーが複合キーの場合はカラム名の配列となります。
            </para>

            <example id="zend.db.table.defining.primary-key.example">

                <title>主キーを指定する例</title>

                <programlisting language="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';
    protected $_primary = 'bug_id';
}
]]></programlisting>

            </example>

            <para>
                主キーを指定しなかった場合は、<classname>Zend_Db_Table_Abstract</classname> は
                <methodname>describeTable()</methodname> メソッドの情報に基づいて主キーを見つけます。
            </para>

            <note>

                <para>
                    すべてのテーブルクラスは、行を一意に決定するために
                    どのカラムを使用するのかを知っている必要があります。
                    テーブルクラスの定義やコンストラクタの引数、
                    あるいは <methodname>describeTable()</methodname>
                    によるメタデータで主キーカラムが定義されていない場合は、
                    そのテーブルを Zend_Db_Table で使用することはできません。
                </para>

            </note>

        </sect3>

        <sect3 id="zend.db.table.defining.setup">

            <title>テーブルの設定メソッドのオーバーライド</title>

            <para>
                テーブルクラスのインスタンスを作成する際に、
                コンストラクタ内でいくつかの protected メソッドをコールします。
                これにより、テーブルのメタデータを初期化します。
                これらのメソッドを拡張して、メタデータを明示的に定義することも可能です。
                その場合は、メソッドの最後で親クラスの同名のメソッドをコールすることを忘れないようにしましょう。
            </para>

            <example id="zend.db.table.defining.setup.example">

                <title>_setupTableName() メソッドのオーバーライドの例</title>

                <programlisting language="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
    protected function _setupTableName()
    {
        $this->_name = 'bugs';
        parent::_setupTableName();
    }
}
]]></programlisting>

            </example>

            <para>
                オーバーライドできるメソッドは、次のとおりです。
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>_setupDatabaseAdapter()</methodname>
                        は、アダプタが設定されているかどうかを調べ、
                        必要に応じてレジストリからデフォルトのアダプタを取得します。
                        このメソッドをオーバーライドすると、
                        データベースアダプタを別の場所から取得できます。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>_setupTableName()</methodname>
                        は、デフォルトのテーブル名をクラス名に設定します。
                        このメソッドをオーバーライドすると、
                        この処理の前にテーブル名を指定することができます。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>_setupMetadata()</methodname>
                        はテーブル名が "schema.table" 形式の場合にスキーマを設定し、
                        <methodname>describeTable()</methodname> をコールしてメタデータ情報を取得します。
                        このメソッドが返す配列のカラム
                        <varname>$_cols</varname> の情報をデフォルトで使用します。
                        このメソッドをオーバーライドすると、カラムを指定することができます。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>_setupPrimaryKey()</methodname>
                        はデフォルトの主キーを <methodname>describeTable()</methodname>
                        から取得した内容に設定し、配列 <varname>$_cols</varname>
                        に主キーカラムが含まれているかどうかを調べます。
                        このメソッドをオーバーライドすると、主キーカラムを指定することができます。
                    </para>
                </listitem>
            </itemizedlist>

        </sect3>

        <sect3 id="zend.db.table.initialization">

            <title>テーブルの初期化</title>

            <para>
                テーブルクラスの作成時にアプリケーション固有のロジックを初期化したい場合は、
                その作業を <methodname>init()</methodname> メソッドで行います。
                これは、テーブルのメタデータがすべて処理された後にコールされます。
                メタデータを変更するつもりがないのなら、<code>__construct</code>
                メソッドよりもこちらを使用することを推奨します。
            </para>

            <example id="zend.db.table.defining.init.usage.example">

                <title>init() メソッドの使用例</title>

                <programlisting language="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_observer;

    public function init()
    {
        $this->_observer = new MyObserverClass();
    }
}
]]></programlisting>

            </example>

        </sect3>

    </sect2>

    <sect2 id="zend.db.table.constructing">

        <title>テーブルのインスタンスの作成</title>

        <para>
            テーブルクラスを使用する前に、コンストラクタでそのインスタンスを作成します。
            コンストラクタの引数はオプションの配列となります。
            テーブルのコンストラクタのオプションのうち、最も重要なのは
            データベースアダプタのインスタンスとなります。
            これは <acronym>RDBMS</acronym> への有効な接続を表します。
            データベースアダプタをテーブルクラスに指定する方法は三通りあります。
            それぞれについて、以下で説明します。
        </para>

        <sect3 id="zend.db.table.constructing.adapter">

            <title>データベースアダプタの指定</title>

            <para>
                データベースアダプタをテーブルクラスに指定する最初の方法は、
                <classname>Zend_Db_Adapter_Abstract</classname> 型のオブジェクトをオプションの配列で渡すことです。
                配列のキーは <code>'db'</code> となります。
            </para>

            <example id="zend.db.table.constructing.adapter.example">

                <title>アダプタオブジェクトを使用した、テーブルの作成の例</title>

                <programlisting language="php"><![CDATA[
$db = Zend_Db::factory('PDO_MYSQL', $options);

$table = new Bugs(array('db' => $db));
]]></programlisting>

            </example>

        </sect3>

        <sect3 id="zend.db.table.constructing.default-adapter">

            <title>デフォルトのデータベースアダプタの設定</title>

            <para>
                データベースアダプタをテーブルクラスに指定する二番目の方法は、
                デフォルトのデータベースアダプタとして <classname>Zend_Db_Adapter_Abstract</classname>
                型のオブジェクトを宣言することです。そのアプリケーション内で、
                これ以降に作成したテーブルインスタンスについてこれが用いられます。
                これを行うには、静的メソッド
                <methodname>Zend_Db_Table_Abstract::setDefaultAdapter()</methodname>
                を使用します。引数は、<classname>Zend_Db_Adapter_Abstract</classname>
                型のオブジェクトとなります。
            </para>

            <example id="zend.db.table.constructing.default-adapter.example">

                <title>デフォルトアダプタを使用した、テーブルの作成の例</title>

                <programlisting language="php"><![CDATA[
$db = Zend_Db::factory('PDO_MYSQL', $options);
Zend_Db_Table_Abstract::setDefaultAdapter($db);

// その後...

$table = new Bugs();
]]></programlisting>

            </example>

            <para>
                これは、たとえば起動ファイルなどでデータベースアダプタオブジェクトを作成し、
                それをデフォルトのアダプタとして保存しておく場合などに便利です。
                これにより、アプリケーション全体で共通のアダプタを使用することが保証されます。
                しかし、デフォルトのアダプタのインスタンスは、ひとつだけしか設定できません。
            </para>

        </sect3>

        <sect3 id="zend.db.table.constructing.registry">

            <title>データベースアダプタのレジストリへの保存</title>

            <para>
                データベースアダプタをテーブルクラスに指定する三番目の方法は、
                文字列ををオプションの配列で渡すことです。
                配列のキーは、この場合も <code>'db'</code> となります。
                この文字列は、静的な <classname>Zend_Registry</classname> インスタンスのキーとして使用します。
                このキーのエントリが <classname>Zend_Db_Adapter_Abstract</classname> 型のオブジェクトとなります。
            </para>

            <example id="zend.db.table.constructing.registry.example">

                <title>レジストリのキーを使用した、テーブルの作成の例</title>

                <programlisting language="php"><![CDATA[
$db = Zend_Db::factory('PDO_MYSQL', $options);
Zend_Registry::set('my_db', $db);

// その後...

$table = new Bugs(array('db' => 'my_db'));
]]></programlisting>

            </example>

            <para>
                デフォルトアダプタの指定と同様、これにより、
                アプリケーション全体で共通のアダプタを使用することが保証されます。
                レジストリには複数のアダプタインスタンスを保存できるため、
                より柔軟に使用できます。指定したアダプタインスタンスは
                特定の <acronym>RDBMS</acronym> やデータベースインスタンスに固有のものとなります。
                複数のデータベースにアクセスする必要がある場合は、
                複数のアダプタが必要です。
            </para>

        </sect3>

    </sect2>

    <sect2 id="zend.db.table.insert">

        <title>テーブルへの行の挿入</title>

        <para>
            テーブルオブジェクトを使用して、そのオブジェクトの元になっているテーブルに
            行を挿入することができます。そのためには、テーブルオブジェクトの
            <methodname>insert()</methodname> メソッドを使用します。引数は連想配列で、
            カラム名と値の対応を指定します。
        </para>

        <example id="zend.db.table.insert.example">

            <title>テーブルへの挿入の例</title>

            <programlisting language="php"><![CDATA[
$table = new Bugs();

$data = array(
    'created_on'      => '2007-03-22',
    'bug_description' => '何かおかしい',
    'bug_status'      => 'NEW'
);

$table->insert($data);
]]></programlisting>

        </example>

        <para>
            デフォルトでは、配列内の値はリテラル値として扱われ、
            パラメータを使用して挿入されます。これを <acronym>SQL</acronym> の式として扱いたい場合は、
            文字列ではない形式で指定する必要があります。その際には
            <classname>Zend_Db_Expr</classname> 型のオブジェクトを使用します。
        </para>

        <example id="zend.db.table.insert.example-expr">

            <title>式をテーブルに挿入する例</title>

            <programlisting language="php"><![CDATA[
$table = new Bugs();

$data = array(
    'created_on'      => new Zend_Db_Expr('CURDATE()'),
    'bug_description' => '何かおかしい',
    'bug_status'      => 'NEW'
);
]]></programlisting>

        </example>

        <para>
            上の例では、テーブルには自動インクリメントの主キーがあるものとします。
            これは <classname>Zend_Db_Table_Abstract</classname> のデフォルトの挙動ですが、
            それ以外の形式の主キーも扱えます。以下の節では、
            さまざまな形式の主キーを扱う方法を説明します。
        </para>

        <sect3 id="zend.db.table.insert.key-auto">

            <title>自動インクリメントのキーを持つテーブルの使用</title>

            <para>
                自動インクリメントの主キーは、<acronym>SQL</acronym> の <constant>INSERT</constant>
                文で主キー列を省略した場合に一意な整数値を生成します。
            </para>

            <para>
                <classname>Zend_Db_Table_Abstract</classname> で protected 変数
                <varname>$_sequence</varname> の値を boolean の <constant>TRUE</constant>
                にすると、そのテーブルは自動インクリメントの主キーを持つものとみなされます。
            </para>

            <example id="zend.db.table.insert.key-auto.example">

                <title>自動インクリメントの主キーを持つテーブルを宣言する例</title>

                <programlisting language="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';

    // これは Zend_Db_Table_Abstract クラスのデフォルト設定です。
    // 特に定義する必要はありません。
    protected $_sequence = true;
}
]]></programlisting>

            </example>

            <para>
                MySQL、Microsoft SQL Server そして SQLite
                などの <acronym>RDBMS</acronym> が、主キーの自動インクリメントをサポートしています。
            </para>

            <para>
                PostgreSQL の <constant>SERIAL</constant> 記法を使用すると、
                テーブル名とカラム名をもとにして暗黙的にシーケンスを定義します。
                新しい行を作成した際にはこのシーケンスを用いてキーの値を生成します。
                IBM DB2 には、これと同等の動作をする <constant>IDENTIFY</constant> という記法があります。
                これらの記法を使用する場合は、<classname>Zend_Db_Table</classname> クラスで
                <varname>$_sequence</varname> を <constant>TRUE</constant> と設定し、
                自動インクリメントを有効にしてください。
            </para>

        </sect3>

        <sect3 id="zend.db.table.insert.key-sequence">

            <title>シーケンスを持つテーブルの使用</title>

            <para>
                シーケンスとはデータベースのオブジェクトの一種で、
                一意な値を生成するものです。これを、
                ひとつあるいは複数のテーブルの主キーの値として使用できます。
            </para>

            <para>
                <varname>$_sequence</varname> に文字列を設定すると、
                <classname>Zend_Db_Table_Abstract</classname> は、それがデータベースの
                シーケンスオブジェクトの名前であるとみなします。
                シーケンスを実行して新しい値を生成し、その値を
                <constant>INSERT</constant> 操作で使用します。
            </para>

            <example id="zend.db.table.insert.key-sequence.example">

                <title>シーケンスを用いたテーブルを宣言する例</title>

                <programlisting language="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';

    protected $_sequence = 'bug_sequence';
}
]]></programlisting>

            </example>

            <para>
                Oracle、PostgreSQL そして IBM DB2 などの <acronym>RDBMS</acronym> が、
                データベースでのシーケンスオブジェクトをサポートしています。
            </para>

            <para>
                PostgreSQL および IBM DB2 は、
                暗黙的にシーケンスを定義してカラムに関連付ける構文もサポートしています。
                この記法を使う場合は、
                そのテーブルで自動インクリメントキーのカラムを使用するようにします。
                シーケンスのキーの次の値を取得することがある場合にのみ
                シーケンス名を文字列で定義します。
            </para>

        </sect3>

        <sect3 id="zend.db.table.insert.key-natural">

            <title>自然キーを持つテーブルの使用</title>

            <para>
                自然キーを持つテーブルもあります。自然キーとは、
                テーブルやシーケンスによって自動生成されるもの以外のキーということです。
                この場合は、主キーの値を指定する必要があります。
            </para>

            <para>
                <varname>$_sequence</varname> の値を boolean の <constant>FALSE</constant>
                にすると、<classname>Zend_Db_Table_Abstract</classname> はそのテーブルが自然キーを持つものとみなします。
                <methodname>insert()</methodname> メソッドを使用する際には、
                主キーカラムの値をデータの配列で指定する必要があります。
                指定しなかった場合、このメソッドは
                <classname>Zend_Db_Table_Exception</classname> をスローします。
            </para>

            <example id="zend.db.table.insert.key-natural.example">

                <title>自然キーを用いたテーブルを宣言する例</title>

                <programlisting language="php"><![CDATA[
class BugStatus extends Zend_Db_Table_Abstract
{
    protected $_name = 'bug_status';

    protected $_sequence = false;
}
]]></programlisting>

            </example>

            <note>

                <para>
                    自然キーのテーブルは、すべての <acronym>RDBMS</acronym> がサポートしています。
                    自然キーを使用するテーブルの例としては、
                    ルックアップテーブルや多対多リレーションの中間テーブル、
                    そして複合主キーを持つ大半のテーブルなどがあります。
                </para>

            </note>

        </sect3>

    </sect2>

    <sect2 id="zend.db.table.update">

        <title>テーブルの行の更新</title>

        <para>
            データベースのテーブルの行を更新するには、テーブルクラスの
            <code>update</code> メソッドを使用します。
            このメソッドには二つの引数を指定します。変更するカラムと
            それらのカラムに代入する新しい値を表す連想配列、
            そして <constant>UPDATE</constant> 操作の対象となる行を指定する
            <constant>WHERE</constant> 句で使用する <acronym>SQL</acronym> 式です。
        </para>

        <example id="zend.db.table.update.example">

            <title>テーブルの行の更新の例</title>

            <programlisting language="php"><![CDATA[
$table = new Bugs();

$data = array(
    'updated_on'      => '2007-03-23',
    'bug_status'      => 'FIXED'
);

$where = $table->getAdapter()->quoteInto('bug_id = ?', 1234);

$table->update($data, $where);
]]></programlisting>

        </example>

        <para>
            テーブルの <methodname>update()</methodname> メソッドはデータベースアダプタの
            <link linkend="zend.db.adapter.write.update"><methodname>update()</methodname></link>
            メソッドへのプロキシなので、
            二番目の引数は、<acronym>SQL</acronym> 式の配列とすることができます。
            その場合、それぞれの式が論理演算子 <constant>AND</constant>
            で連結されます。
        </para>

        <note>

            <para>
                <acronym>SQL</acronym> 式の中の値や識別子は、自動的にはクォートされません。
                クォートが必要な値や識別子を使用する場合は、自分でクォートする必要があります。
                データベースアダプタの <methodname>quote()</methodname>、<methodname>quoteInto()</methodname>
                および <methodname>quoteIdentifier()</methodname> を使用してください。
            </para>

        </note>

    </sect2>

    <sect2 id="zend.db.table.delete">

        <title>テーブルからの行の削除</title>

        <para>
            データベースのテーブルから行を削除するには、テーブルクラスの
            <methodname>delete()</methodname> メソッドを使用します。
            このメソッドにはひとつの引数を指定します。この引数は
            <constant>WHERE</constant> 句で使用する <acronym>SQL</acronym> 式で、
            これにより、削除対象となる行を指定します。
        </para>

        <example id="zend.db.table.delete.example">

            <title>テーブルからの行の削除の例</title>

            <programlisting language="php"><![CDATA[
$table = new Bugs();

$where = $table->getAdapter()->quoteInto('bug_id = ?', 1235);

$table->delete($where);
]]></programlisting>

        </example>

        <para>
            テーブルの <methodname>delete()</methodname> メソッドはデータベースアダプタの
            <link linkend="zend.db.adapter.write.delete"><methodname>delete()</methodname></link>
            メソッドへのプロキシなので、
            引数は <acronym>SQL</acronym> 式の配列とすることもできます。
            その場合、それぞれの式が論理演算子 <constant>AND</constant>
            で連結されます。
        </para>

        <note>

            <para>
                <acronym>SQL</acronym> 式の中の値や識別子は、自動的にはクォートされません。
                クォートが必要な値や識別子を使用する場合は、自分でクォートする必要があります。
                データベースアダプタの <methodname>quote()</methodname>、<methodname>quoteInto()</methodname>
                および <methodname>quoteIdentifier()</methodname> を使用してください。
            </para>

        </note>

    </sect2>

    <sect2 id="zend.db.table.find">

        <title>主キーによる行の検索</title>

        <para>
            データベースのテーブルに対して、指定した主キーの値に対応する行を問い合わせるには
            <methodname>find()</methodname> メソッドを使用します。
            このメソッドの最初の引数は、テーブルの主キーに対応する
            単一の値か、あるいは複数の値の配列となります。
        </para>

        <example id="zend.db.table.find.example">

            <title>主キーの値によって行を捜す例</title>

            <programlisting language="php"><![CDATA[
$table = new Bugs();

// 単一の行を探し、
// Rowset を返します
$rows = $table->find(1234);

// 複数の行を探し、
// こちらも Rowset を返します
$rows = $table->find(array(1234, 5678));
]]></programlisting>

        </example>

        <para>
            単一の値を指定した場合は、このメソッドが返す行数は最大でも一行になります。
            主キーの値が重複することはないので、指定した値に対応する行は
            テーブル内で最大でも一行だけだからです。
            複数の値を配列で指定した場合は、このメソッドが返す結果の最大数は
            配列で指定した値の数となります。
        </para>

        <para>
            <methodname>find()</methodname> メソッドの返す行数は、主キーで指定した値より少なくなるかもしれません。
            たとえば指定した値に対応する行がデータベースのテーブルに存在しなかった場合などです。
            このメソッドが返す行数がゼロになる可能性もあります。
            このように結果の行数が可変なので、<methodname>find()</methodname>
            メソッドが返すオブジェクトの型は <classname>Zend_Db_Table_Rowset_Abstract</classname>
            となります。
        </para>

        <para>
            主キーが複合キーの場合、つまり複数のカラムから構成されるキーの場合は、
            追加のカラムを <methodname>find()</methodname> メソッドの引数で指定します。
            テーブルの主キーのカラム数と同じ数の引数を指定しなければなりません。
        </para>

        <para>
            複合主キーのテーブルから複数行を取得するには、
            各引数を配列で指定します。これらすべての配列の要素数は同じでなければなりません。
            各配列の値が、その順にキー列の値として用いられます。
            たとえば、すべての配列の最初の要素で複合主キーの最初の値を指定し、
            すべての配列の二番目の要素で複合主キーの二番目の値を設定し、……
            というようになります。
        </para>

        <example id="zend.db.table.find.example-compound">

            <title>複合主キーの値の指定による行の取得の例</title>

            <para>
                以下の <methodname>find()</methodname> メソッドは、データベース内のふたつの行にマッチします。
                最初の行の主キーの値は (1234, 'ABC') で、次の行の主キーの値は
                (5678, 'DEF') となります。
            </para>

            <programlisting language="php"><![CDATA[
class BugsProducts extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs_products';
    protected $_primary = array('bug_id', 'product_id');
}

$table = new BugsProducts();

// 単一の行を複合主キーで探し、
// Rowset を返します
$rows = $table->find(1234, 'ABC');

// 複数の行を複合主キーで探し、
// こちらも Rowset を返します
$rows = $table->find(array(1234, 5678), array('ABC', 'DEF'));
]]></programlisting>

        </example>

    </sect2>

    <sect2 id="zend.db.table.fetch-all">

        <title>行セットの問い合わせ</title>

        <sect3 id="zend.db.table.fetch-all.select">

            <title>Select API</title>

            <para>

                <warning>

                    <para>
                        取得操作用の <acronym>API</acronym> は変更され、
                        <classname>Zend_Db_Table_Select</classname> オブジェクトでクエリを変更できるようになりました。
                        しかし、昔ながらの方法である <methodname>fetchRow()</methodname> や
                        <methodname>fetchAll()</methodname> は今でも同じように使用することができます。
                    </para>

                    <para>
                        次の文は、どれも正しくて同じ動作をします。
                        しかし、新しい使用法に対応するためにもできるだけ新しい書き方に変更することをお勧めします。
                    </para>

                    <para>

                        <programlisting language="php"><![CDATA[
// 行セットを取得します
$rows = $table->fetchAll(
    'bug_status = "NEW"',
    'bug_id ASC',
    10,
    0
    );
$rows = $table->fetchAll(
    $table->select()
        ->where('bug_status = ?', 'NEW')
        ->order('bug_id ASC')
        ->limit(10, 0)
    );

// 単一の行を取得します
$row = $table->fetchRow(
    'bug_status = "NEW"',
    'bug_id ASC'
    );
$row = $table->fetchRow(
    $table->select()
        ->where('bug_status = ?', 'NEW')
        ->order('bug_id ASC')
    );
]]></programlisting>

                    </para>

                </warning>

            </para>

            <para>
                <classname>Zend_Db_Table_Select</classname> オブジェクトは
                <classname>Zend_Db_Select</classname> を継承したものであり、
                クエリにはいくつか制限があります。追加された機能や制限事項を以下にまとめます。
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        fetchRow あるいは fetchAll のクエリで、カラムのサブセットを返すことが
                        <emphasis>できます</emphasis>。
                        結果が巨大なものになるけれどもその中には使用しないカラムもある
                        といった場合に有用です。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        select する際に、式の結果をカラムとして指定することが
                        <emphasis>できます</emphasis>。
                        しかし、この場合は行 (あるいは行セット) は
                        <property>readOnly</property> となり、save()
                        することはできません。<property>readOnly</property> な
                        <classname>Zend_Db_Table_Row</classname> に対して
                        <methodname>save()</methodname> を実行しようとすると、例外がスローされます。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        select で JOIN 句を使用して、複数テーブルからの検索を行うことが
                        <emphasis>できます</emphasis>。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        JOIN したテーブルのカラムを結果の行や行セットに指定することは
                        <emphasis>できません</emphasis>。
                        そうすると、PHP のエラーが発生します。
                        これにより、<classname>Zend_Db_Table</classname>
                        の整合性が保証されます。つまり、
                        <classname>Zend_Db_Table_Row</classname> はその親のテーブルのカラムしか参照しないということです。
                    </para>
                </listitem>
            </itemizedlist>

            <para>

                <example id="zend.db.table.qry.rows.set.simple.usage.example">

                    <title>単純な使用法</title>

                    <programlisting language="php"><![CDATA[
$table = new Bugs();

$select = $table->select();
$select->where('bug_status = ?', 'NEW');

$rows = $table->fetchAll($select);
]]></programlisting>

                </example>

            </para>

            <para>
                このコンポーネントでは「流れるようなインターフェイス」
                を実装しているので、この例はもっと省略して書くこともできます。
            </para>

            <para>

                <example id="zend.db.table.qry.rows.set.fluent.interface.example">

                    <title>流れるようなインターフェイスの例</title>

                    <programlisting language="php"><![CDATA[
$table = new Bugs();

$rows =
    $table->fetchAll($table->select()->where('bug_status = ?', 'NEW'));
]]></programlisting>

                </example>

            </para>

        </sect3>

        <sect3 id="zend.db.table.fetch-all.usage">

            <title>行セットの取得</title>

            <para>
                主キーの値以外を条件として行のセットを問い合わせるには、
                テーブルクラスの <methodname>fetchAll()</methodname> メソッドを使用します。
                このメソッドは、<classname>Zend_Db_Table_Rowset_Abstract</classname>
                型のオブジェクトを返します。
            </para>

            <example id="zend.db.table.qry.rows.set.finding.row.example">

                <title>式から行を取得する例</title>

                <programlisting language="php"><![CDATA[
$table = new Bugs();

$select = $table->select()->where('bug_status = ?', 'NEW');

$rows = $table->fetchAll($select);
]]></programlisting>

            </example>

            <para>
                <code>ORDER BY</code> での並べ替えの条件句やオフセットを表す整数値を指定して、
                クエリの返す結果を絞りこむことができます。
                これらの値は <constant>LIMIT</constant> 句で用いられます。
                <constant>LIMIT</constant> 構文をサポートしていない <acronym>RDBMS</acronym>
                では、それと同等のロジックで用いられます。
            </para>

            <example id="zend.db.table.fetch-all.example2">

                <title>式を使用した行の検索の例</title>

                <programlisting language="php"><![CDATA[
$table = new Bugs();

$order  = 'bug_id';

// 21 番目から 30 番目の行を返します
$count  = 10;
$offset = 20;

$select = $table->select()->where(array('bug_status = ?' => 'NEW'))
                          ->order($order)
                          ->limit($count, $offset);

$rows = $table->fetchAll($select);
]]></programlisting>

            </example>

            <para>
                これらのオプションはどれも、必須ではありません。
                ORDER 句を省略した場合は、結果セットに複数の行が含まれる場合の並び順は予測不可能です。
                LIMIT 句を省略した場合は、WHERE 句にマッチするすべての行を取得することになります。
            </para>

        </sect3>

        <sect3 id="zend.db.table.advanced.usage">

            <title>高度な使用法</title>

            <para>
                リクエストの内容をより明確に指定して最適化するために、
                行/行セットが返すカラムの数を絞り込みたいこともあるでしょう。
                これは、select オブジェクトの FROM 句で行います。
                FROM 句の最初の引数は <classname>Zend_Db_Select</classname> オブジェクトと同じですが、
                さらに <classname>Zend_Db_Table_Abstract</classname>
                のインスタンスを渡すこともでき、テーブル名を自動的に検出します。
            </para>

            <para>

                <example id="zend.db.table.qry.rows.set.retrieving.a.example">

                    <title>指定したカラムの取得</title>

                    <programlisting language="php"><![CDATA[
$table = new Bugs();

$select = $table->select();
$select->from($table, array('bug_id', 'bug_description'))
       ->where('bug_status = ?', 'NEW');

$rows = $table->fetchAll($select);
]]></programlisting>

                </example>

            </para>

            <para>

                <important>

                    <para>
                        この状態でも、行セット自体は '正しい' 形式です。
                        単にひとつのテーブルの中の一部のカラムを含んでいるというだけです。
                        この中の行に対して save() メソッドをコールすると、
                        そこに含まれているフィールドだけを更新します。
                    </para>

                </important>

                FROM 句で式を指定すると、その結果を readOnly の行/行セット
                として返します。この例では、bugs テーブルを検索して
                個人別のバグの報告件数を取得しています。
                GROUP 句に注目しましょう。これで、返される行に
                'count' というカラムが含まれるようになり、
                スキーマの他のカラムと同じようにアクセスできるようになります。
            </para>

            <para>

                <example id="zend.db.table.qry.rows.set.retrieving.b.example">

                    <title>式の結果をカラムとして取得する</title>

                    <programlisting language="php"><![CDATA[
$table = new Bugs();

$select = $table->select();
$select->from($table,
              array('COUNT(reported_by) as `count`', 'reported_by'))
       ->where('bug_status = ?', 'NEW')
       ->group('reported_by');

$rows = $table->fetchAll($select);
]]></programlisting>

                </example>

                クエリの一部にルックアップテーブルを使用し、
                より絞り込んで取得することもできます。
                この例では、検索時に accounts テーブルを使用して
                'Bob' が報告したすべてのバグを探しています。
            </para>

            <para>

                <example id="zend.db.table.qry.rows.set.refine.example">

                    <title>ルックアップテーブルによる fetchAll() の結果の絞込み</title>

                    <programlisting language="php"><![CDATA[
$table = new Bugs();

// join する際には、from 部を指定して取得するのが重要です
$select = $table->select(Zend_Db_Table::SELECT_WITH_FROM_PART);
$select->setIntegrityCheck(false)
       ->where('bug_status = ?', 'NEW')
       ->join('accounts', 'accounts.account_name = bugs.reported_by')
       ->where('accounts.account_name = ?', 'Bob');

$rows = $table->fetchAll($select);
]]></programlisting>

                </example>

            </para>

            <para>
                <classname>Zend_Db_Table_Select</classname> の主な使用目的は、
                制約を強要して正しい形式の SELECT クエリを作成することです。
                しかし時には、<classname>Zend_Db_Table_Row</classname> の柔軟性が必要であって
                行を更新したり削除したりすることはないということもあります。
                そんな場合には、setIntegrityCheck に false
                を渡して行/行セットを取得することができます。
                この場合に返される行/行セットは 'ロックされた' 行
                (save()、delete() やフィールドの設定用メソッドを実行すると例外が発生する)
                となります。
            </para>

            <example id="zend.db.table.qry.rows.set.integrity.example">

                <title>Zend_Db_Table_Select の整合性チェックを削除し、JOIN した行を許可する</title>

                <programlisting language="php"><![CDATA[
$table = new Bugs();

$select = $table->select(Zend_Db_Table::SELECT_WITH_FROM_PART)
                ->setIntegrityCheck(false);
$select->where('bug_status = ?', 'NEW')
       ->join('accounts',
              'accounts.account_name = bugs.reported_by',
              'account_name')
       ->where('accounts.account_name = ?', 'Bob');

$rows = $table->fetchAll($select);
]]></programlisting>

            </example>

        </sect3>

    </sect2>

    <sect2 id="zend.db.table.fetch-row">

        <title>単一の行の問い合わせ</title>

        <para>
            <methodname>fetchAll()</methodname> と同じような条件を指定して、
            単一の行を問い合わせることができます。
        </para>

        <example id="zend.db.table.fetch-row.example1">

            <title>式から単一の行を取得する例</title>

            <programlisting language="php"><![CDATA[
$table = new Bugs();

$select  = $table->select()->where('bug_status = ?', 'NEW')
                           ->order('bug_id');

$row = $table->fetchRow($select);
]]></programlisting>

        </example>

        <para>
            このメソッドは、<classname>Zend_Db_Table_Row_Abstract</classname> 型のオブジェクトを返します。
            指定した検索条件に一致する行がデータベースのテーブルにない場合は、
            <methodname>fetchRow()</methodname> は <acronym>PHP</acronym> の <constant>NULL</constant> 値を返します。
        </para>

    </sect2>

    <sect2 id="zend.db.table.info">

        <title>テーブルのメタデータ情報の取得</title>

        <para>
            <classname>Zend_Db_Table_Abstract</classname> クラスは、メタデータに関するいくつかの情報を提供します。
            <methodname>info()</methodname> メソッドは配列を返し、その中には
            テーブルについての情報、カラムや主キー、その他のメタデータが含まれます。
        </para>

        <example id="zend.db.table.info.example">

            <title>テーブル名を取得する例</title>

            <programlisting language="php"><![CDATA[
$table = new Bugs();

$info = $table->info();

echo "テーブル名は " . $info['name'] . " です\n";
]]></programlisting>

        </example>

        <para>
            <methodname>info()</methodname> メソッドが返す配列のキーについて、
            以下にまとめます。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>name</emphasis> =>
                    テーブルの名前。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>cols</emphasis> =>
                    テーブルのカラム名を表す配列。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>primary</emphasis> =>
                    主キーのカラム名を表す配列。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>metadata</emphasis> =>
                    カラム名とカラムに関する情報を関連付けた連想配列。
                    これは <methodname>describeTable()</methodname> メソッドが返す情報です。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>rowClass</emphasis> =>
                    このテーブルインスタンスのメソッドが返す行オブジェクトで使用する
                    具象クラス名。デフォルトは <classname>Zend_Db_Table_Row</classname> です。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>rowsetClass</emphasis> =>
                    このテーブルインスタンスのメソッドが返す行セットオブジェクトで使用する
                    具象クラス名。デフォルトは <classname>Zend_Db_Table_Rowset</classname> です。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>referenceMap</emphasis> =>
                    このテーブルから任意の親テーブルに対する参照の情報を含む連想配列。
                    <xref linkend="zend.db.table.relationships.defining" />
                    を参照ください。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>dependentTables</emphasis> =>
                    このテーブルを参照しているテーブルのクラス名の配列。
                    <xref linkend="zend.db.table.relationships.defining" />
                    を参照ください。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>schema</emphasis> =>
                    テーブルのスキーマ (あるいはデータベース、あるいは表領域)
                    の名前。
                </para>
            </listitem>
        </itemizedlist>

    </sect2>

    <sect2 id="zend.db.table.metadata.caching">

        <title>テーブルのメタデータのキャッシュ</title>

        <para>
            デフォルトでは <classname>Zend_Db_Table_Abstract</classname> の問合せ先は
            テーブルオブジェクトのインスタンスの
            <link linkend="zend.db.table.info">テーブルメタデータ</link>
            が指すデータベースとなります。
            つまり、テーブルオブジェクトを作成する際にデフォルトで行われれることは、アダプタの
            <methodname>describeTable()</methodname> メソッドによってデータベースからテーブルのメタデータを取得するということになります。
            これを必要とする操作には次のようなものがあります。
        </para>

        <itemizedlist>
            <listitem><para><methodname>insert()</methodname></para></listitem>

            <listitem><para><methodname>find()</methodname></para></listitem>

            <listitem><para><methodname>info()</methodname></para></listitem>
        </itemizedlist>

        <para>
            同一のテーブルに対して複数のテーブルオブジェクトを作成する場合などに、
            毎回テーブルのめたデータをデータベースに問い合わせることは
            パフォーマンスの観点からも好ましくありません。
            このような場合のために、データベースから取得したテーブルメタデータをキャッシュしておくことができます。
        </para>

        <para>
            テーブルのメタデータをキャッシュする主な方法は、次のふたつです。

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis><methodname>Zend_Db_Table_Abstract::setDefaultMetadataCache()</methodname> をコールする</emphasis> -
                        これは、すべてのテーブルクラスで使用するデフォルトのキャッシュオブジェクトを一度で設定できます。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis><methodname>Zend_Db_Table_Abstract::__construct()</methodname> を設定する</emphasis> -
                        これは、特定のテーブルクラスのインスタンスでh使用するキャッシュオブジェクトを設定できます。
                    </para>
                </listitem>
            </itemizedlist>

            どちらの場合においても、メソッドの引数はひとつで、<constant>NULL</constant> (キャッシュを使用しない)
            あるいは <link linkend="zend.cache.frontends.core"><classname>Zend_Cache_Core</classname></link>
            のインスタンスを指定します。これらを組み合わせることで、
            デフォルトのメタデータキャッシュを指定した上で
            特定のテーブルオブジェクトについてのみ別のキャッシュを使用させることができます。
        </para>

        <example id="zend.db.table.metadata.caching-default">

            <title>すべてのテーブルオブジェクトでのデフォルトのメタデータキャッシュの使用</title>

            <para>
                次のコードは、デフォルトのメタデータキャッシュをすべてのテーブルオブジェクトで使用する方法を示すものです。
            </para>

            <programlisting language="php"><![CDATA[
// まずキャッシュを作成します
$frontendOptions = array(
    'automatic_serialization' => true
    );

$backendOptions  = array(
    'cache_dir'                => 'cacheDir'
    );

$cache = Zend_Cache::factory('Core',
                             'File',
                             $frontendOptions,
                             $backendOptions);

// 次に、それをすべてのテーブルオブジェクトで使用するように設定します
Zend_Db_Table_Abstract::setDefaultMetadataCache($cache);

// テーブルクラスも必要です
class Bugs extends Zend_Db_Table_Abstract
{
    // ...
}

// Bugs の各インスタンスは、これでデフォルトのメタデータキャッシュを用いるようになります
$bugs = new Bugs();
]]></programlisting>

        </example>

        <example id="zend.db.table.metadata.caching-instance">

            <title>特定のテーブルオブジェクトでのメタデータキャッシュの使用</title>

            <para>
                次のコードは、メタデータキャッシュを特定のテーブルオブジェクトに設定する方法を示すものです。
            </para>

            <programlisting language="php"><![CDATA[
// まずキャッシュを作成します
$frontendOptions = array(
    'automatic_serialization' => true
    );

$backendOptions  = array(
    'cache_dir'                => 'cacheDir'
    );

$cache = Zend_Cache::factory('Core',
                             'File',
                             $frontendOptions,
                             $backendOptions);

// テーブルクラスも必要です
class Bugs extends Zend_Db_Table_Abstract
{
    // ...
}

// インスタンスを設定します
$bugs = new Bugs(array('metadataCache' => $cache));
]]></programlisting>

        </example>

        <note>

            <title>キャッシュのフロントエンドにおける自動シリアライズ</title>

            <para>
                アダプタの describeTable() メソッドの返す内容は配列なので、
                <classname>Zend_Cache_Core</classname> フロントエンドのオプション
                <code>automatic_serialization</code> は <constant>TRUE</constant> と設定しましょう。
            </para>

        </note>

        <para>
            上の例では <classname>Zend_Cache_Backend_File</classname> を使用していますが、
            状況に応じて適切なバックエンドを使い分けることができます。詳細な情報は
            <link linkend="zend.cache">Zend_Cache</link> を参照ください。
        </para>

        <sect3 id="zend.db.table.metadata.caching.hardcoding">
            <title>テーブルのメタデータのハードコーディング</title>

            <para>
                メタデータのキャッシュをより高速にするために、
                メタデータをハードコーディングすることもできます。
                しかし、そうすると、
                テーブルのスキーマが変わるたびにコードを変更しなければならなくなります。
                この方法をおすすめできるのは、
                実運用環境で最適化が必要となった場合のみです。
            </para>

            <para>
                メタデータの構造は次のようになります。
            </para>

            <programlisting language="php"><![CDATA[
protected $_metadata = array(
    '<column_name>' => array(
        'SCHEMA_NAME'      => <string>,
        'TABLE_NAME'       => <string>,
        'COLUMN_NAME'      => <string>,
        'COLUMN_POSITION'  => <int>,
        'DATA_TYPE'        => <string>,
        'DEFAULT'          => NULL|<value>,
        'NULLABLE'         => <bool>,
        'LENGTH'           => <string - length>,
        'SCALE'            => NULL|<value>,
        'PRECISION'        => NULL|<value>,
        'UNSIGNED'         => NULL|<bool>,
        'PRIMARY'          => <bool>,
        'PRIMARY_POSITION' => <int>,
        'IDENTITY'         => <bool>,
    ),
    // さらなるカラム...
);
]]></programlisting>

            <para>
                適切な値を知るには、メタデータキャッシュを使用するのが簡単でしょう。
                キャッシュに格納された値をデシリアライズするのです。
            </para>

            <para>
                この最適化を無効にするには、
                <code>metadataCacheInClass</code> フラグをオフにします。
            </para>

            <programlisting language="php"><![CDATA[
// インスタンス作成時
$bugs = new Bugs(array('metadataCacheInClass' => false));

// その後
$bugs->setMetadataCacheInClass(false);
]]></programlisting>

            <para>
                このフラグはデフォルトで有効になっています。この場合は、
                <varname>$_metadata</varname> 配列はインスタンスの作成時にのみ作成されます。
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.db.table.extending">

        <title>テーブルクラスのカスタマイズおよび拡張</title>

        <sect3 id="zend.db.table.extending.row-rowset">

            <title>独自の行クラスあるいは行セットクラスの使用</title>

            <para>
                デフォルトでは、テーブルクラスが返す行セットは
                具象クラス <classname>Zend_Db_Table_Rowset</classname> のインスタンスであり、
                行セットには具象クラス <classname>Zend_Db_Table_Row</classname>
                のインスタンスの集合が含まれます。
                これらのいずれについても、別のクラスを使用することが可能です。
                しかし、使用するクラスはそれぞれ
                <classname>Zend_Db_Table_Rowset_Abstract</classname> および
                <classname>Zend_Db_Table_Row_Abstract</classname> を継承したものでなければなりません。
            </para>

            <para>
                行クラスおよび行セットクラスを指定するには、
                テーブルのコンストラクタのオプション配列を使用します。
                対応するキーは、それぞれ
                <code>'rowClass'</code> および
                <code>'rowsetClass'</code> となります。
                ここには、クラスの名前を文字列で指定します。
            </para>

            <example id="zend.db.table.extending.row-rowset.example">

                <title>行クラスおよび行セットクラスの指定の例</title>

                <programlisting language="php"><![CDATA[
class My_Row extends Zend_Db_Table_Row_Abstract
{
    ...
}

class My_Rowset extends Zend_Db_Table_Rowset_Abstract
{
    ...
}

$table = new Bugs(
    array(
        'rowClass'    => 'My_Row',
        'rowsetClass' => 'My_Rowset'
    )
);

$where = $table->getAdapter()->quoteInto('bug_status = ?', 'NEW')

// My_Rowset 型のオブジェクトを返します。
// その中には My_Row 型のオブジェクトの配列が含まれます。
$rows = $table->fetchAll($where);
]]></programlisting>

            </example>

            <para>
                クラスを変更するには、<methodname>setRowClass()</methodname> メソッドおよび
                <methodname>setRowsetClass()</methodname> メソッドを使用します。
                これは、それ以降に作成される行および行セットに適用されます。
                すでに出来上がっている行オブジェクトや行セットオブジェクトには
                何の影響も及ぼしません。
            </para>

            <example id="zend.db.table.extending.row-rowset.example2">

                <title>行クラスおよび行セットクラスの変更の例</title>

                <programlisting language="php"><![CDATA[
$table = new Bugs();

$where = $table->getAdapter()->quoteInto('bug_status = ?', 'NEW')

// Zend_Db_Table_Rowset 型のオブジェクトを返します。
// その中には Zend_Db_Table_Row 型のオブジェクトの配列が含まれます。
$rowsStandard = $table->fetchAll($where);

$table->setRowClass('My_Row');
$table->setRowsetClass('My_Rowset');

// My_Rowset 型のオブジェクトを返します。
// その中には My_Row 型のオブジェクトの配列が含まれます。
$rowsCustom = $table->fetchAll($where);

// $rowsStandard オブジェクトはまだ存在しますが、なにも変更されていません
]]></programlisting>

            </example>

            <para>
                行クラスおよび行セットクラスについての詳細は
                <xref linkend="zend.db.table.row" /> および
                <xref linkend="zend.db.table.rowset" /> を参照ください。
            </para>

        </sect3>

        <sect3 id="zend.db.table.extending.insert-update">

            <title>Insert、Update および Delete 時の独自ロジックの定義</title>

            <para>
                テーブルクラスの <methodname>insert()</methodname> メソッドや
                <methodname>update()</methodname> メソッドをオーバーライドすることができます。
                これにより、データベース操作の前に実行される独自のコードを実装することができます。
                最後に親クラスのメソッドをコールすることを忘れないようにしましょう。
            </para>

            <example id="zend.db.table.extending.insert-update.example">

                <title>タイムスタンプを処理する独自ロジック</title>

                <programlisting language="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';

    public function insert(array $data)
    {
        // タイムスタンプを追加します
        if (empty($data['created_on'])) {
            $data['created_on'] = time();
        }
        return parent::insert($data);
    }

    public function update(array $data, $where)
    {
        // タイムスタンプを追加します
        if (empty($data['updated_on'])) {
            $data['updated_on'] = time();
        }
        return parent::update($data, $where);
    }
}
]]></programlisting>

            </example>

            <para>
                <methodname>delete()</methodname> メソッドをオーバーライドすることもできます。
            </para>

        </sect3>

        <sect3 id="zend.db.table.extending.finders">

            <title>Zend_Db_Table における独自の検索メソッドの定義</title>

            <para>
                もし特定の条件によるテーブルの検索を頻繁に行うのなら、
                独自の検索メソッドをテーブルクラスで実装することができます。
                大半の問い合わせは <methodname>fetchAll()</methodname>
                を用いて書くことができますが、
                アプリケーション内の複数の箇所でクエリを実行する場合には
                問い合わせ条件を指定するコードが重複してしまいます。
                そんな場合は、テーブルクラスでメソッドを実装し、
                よく使う問い合わせを定義しておいたほうが便利です。
            </para>

            <example id="zend.db.table.extending.finders.example">

                <title>状況を指定してバグを検索する独自メソッド</title>

                <programlisting language="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';

    public function findByStatus($status)
    {
        $where = $this->getAdapter()->quoteInto('bug_status = ?', $status);
        return $this->fetchAll($where, 'bug_id');
    }
}
]]></programlisting>

            </example>

        </sect3>

        <sect3 id="zend.db.table.extending.inflection">

            <title>Zend_Db_Table における語尾変化の定義</title>

            <para>
                テーブルのクラス名を <acronym>RDBMS</acronym> のテーブル名とあわせるために、
                <emphasis>inflection (語尾変化)</emphasis>
                と呼ばれる文字列変換を使用することを好む方もいます。
            </para>

            <para>
                たとえば、テーブルのクラス名が
                "<code>BugsProducts</code>" だとすると、クラスのプロパティ
                <varname>$_name</varname> を明示的に宣言しなかった場合は
                データベース内の物理的なテーブル
                "<code>bugs_products</code>" にマッチします。この関連付けでは、
                "CamelCase" 形式のクラス名が小文字に変換され、単語の区切りがアンダースコアに変わります。
            </para>

            <para>
                データベースのテーブル名を、クラス名とは独立したものにすることもできます。
                その場合は、テーブルクラスのプロパティ <varname>$_name</varname>
                に、そのクラス名を指定します。
            </para>

            <para>
                <classname>Zend_Db_Table_Abstract</classname> は、クラス名とテーブル名を関連付けるための語尾変化は行いません。
                テーブルクラスで <varname>$_name</varname> の宣言を省略すると、
                そのクラス名に正確に一致する名前のテーブルと関連付けられます。
            </para>

            <para>
                データベースの識別子を変換することは、適切ではありません。
                なぜなら、それは不明確な状態を引き起こし、
                時には識別子にアクセスできなくなってしまうからです。
                <acronym>SQL</acronym> の識別子をデータベース内にあるそのままの形式で扱うことで、
                <classname>Zend_Db_Table_Abstract</classname> はシンプルで柔軟なものになっています。
            </para>

            <para>
                語尾変化を行いたい場合は、その変換を独自に実装しなければなりません。そのためには
                テーブルクラスで <methodname>_setupTableName()</methodname> メソッドをオーバーライドします。
                これを行うひとつの方法としては、<classname>Zend_Db_Table_Abstract</classname>
                を継承した抽象クラスを作成し、さらにそれを継承したテーブルクラスを作成するという方法があります。
            </para>

            <example id="zend.db.table.extending.inflection.example">

                <title>語尾変化を実装した抽象テーブルクラスの例</title>

                <programlisting language="php"><![CDATA[
abstract class MyAbstractTable extends Zend_Db_Table_Abstract
{
    protected function _setupTableName()
    {
        if (!$this->_name) {
            $this->_name = myCustomInflector(get_class($this));
        }
        parent::_setupTableName();
    }
}

class BugsProducts extends MyAbstractTable
{
}
]]></programlisting>

            </example>

            <para>
                語尾変化を行う関数を書くのはあなたの役割です。
                Zend Framework にはそのような関数はありません。
            </para>

        </sect3>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->