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

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

    <title>Zend_Db_Statement</title>

    <para>
        <xref linkend="zend.db.adapter" /> で説明した
        <code>fetchAll()</code> や <code>insert()</code>
        のような便利なメソッド以外にも、
        ステートメントオブジェクトを使用することで、
        より柔軟にクエリの実効や結果の取得ができるようになります。
        ここでは、ステートメントオブジェクトを取得してそのメソッドを使用する方法を説明します。
    </para>

    <para>
        <classname>Zend_Db_Statement</classname> は、
        <ulink url="http://www.php.net/pdo">PHP Data Objects</ulink>
        拡張モジュールの PDOStatement オブジェクトをもとにしたものです。
    </para>

    <sect2 id="zend.db.statement.creating">

        <title>ステートメントの作成</title>

        <para>
            通常は、ステートメントオブジェクトはデータベースアダプタクラスの
            <code>query()</code> メソッドの返り値として取得します。
            このメソッドは、任意の SQL 文を実行することができます。
            最初の引数には SQL 文を指定し、
            オプションの二番目の引数には SQL 文中のプレースホルダを置き換える
            バインド変数の配列を指定します。
        </para>

        <example id="zend.db.statement.creating.example1">
            <title>query() による SQL ステートメントオブジェクトの作成</title>
            <programlisting role="php"><![CDATA[
$stmt = $db->query(
            'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?',
            array('goofy', 'FIXED')
        );
]]>
            </programlisting>
        </example>

        <para>
            ステートメントオブジェクトは、準備された SQL 文に対して
            変数の値をバインドして一度実行したものに対応します。
            そのステートメントが SELECT クエリあるいは何らかの結果セットを返すものであった場合は、
            すでに結果を取得する準備ができています。
        </para>

        <para>
            ステートメントオブジェクトをコンストラクタから作成することもできますが、
            あまり一般的ではありません。このオブジェクトを作成するための
            ファクトリメソッドはないので、特定のステートメントクラスを読み込んで
            そのコンストラクタをコールすることになります。
            コンストラクタの最初の引数にはアダプタオブジェクトを指定し、
            二番目の引数には SQL 文を文字列で指定します。
            このステートメントは、準備されただけでまだ実行されていない状態となります。
        </para>

        <example id="zend.db.statement.creating.example2">
            <title>SQL ステートメントのコンストラクタの使用</title>
            <programlisting role="php"><![CDATA[
$sql = 'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?';

$stmt = new Zend_Db_Statement_Mysqli($db, $sql);
]]>
            </programlisting>
        </example>

    </sect2>

    <sect2 id="zend.db.statement.executing">

        <title>ステートメントの実行</title>

        <para>
            ステートメントをコンストラクタから作成した場合や、
            一度実行したステートメントをもう一度実行したい場合などは、
            ステートメントオブジェクトを自分で実行する必要があります。
            その場合は、ステートメントオブジェクトの <code>execute()</code>
            メソッドを使用します。このメソッドに渡す引数は、
            ステートメント中のプレースホルダにバインドする変数の値の配列となります。
        </para>

        <para>
            <emphasis>位置指定によるパラメータ</emphasis>、
            つまりクエスチョンマーク (<code>?</code>) でパラメータを指定している場合は、
            バインドする値は通常の配列で渡します。
        </para>

        <example id="zend.db.statement.executing.example1">
            <title>位置指定パラメータによるステートメントの実行</title>
            <programlisting role="php"><![CDATA[
$sql = 'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?';

$stmt = new Zend_Db_Statement_Mysqli($db, $sql);

$stmt->execute(array('goofy', 'FIXED'));
]]>
            </programlisting>
        </example>

        <para>
            <emphasis>名前つきパラメータ</emphasis>、
            つまり先頭にコロン (<code>:</code>) をつけた識別子で
            パラメータを指定している場合は、バインドする値を連想配列で渡します。
            配列のキーが、パラメータの名前に対応します。
        </para>

        <example id="zend.db.statement.executing.example2">
            <title>名前つきパラメータによるステートメントの実行</title>
            <programlisting role="php"><![CDATA[
$sql = 'SELECT * FROM bugs WHERE ' .
       'reported_by = :reporter AND bug_status = :status';

$stmt = new Zend_Db_Statement_Mysqli($db, $sql);

$stmt->execute(array(':reporter' => 'goofy', ':status' => 'FIXED'));
]]>
            </programlisting>
        </example>

        <para>
            PDO のステートメントは位置指定パラメータと名前つきパラメータの両方をサポートしています。
            しかし、ひとつの SQL の中で両方を使用することはできません。
            <classname>Zend_Db_Statement</classname> クラスの中には PDO を使用していないものもありますが、
            それらの中にはいずれか一種類の形式のパラメータしかサポートしないものもあるかもしれません。
        </para>

    </sect2>

    <sect2 id="zend.db.statement.fetching">

        <title><code>SELECT</code> 文からの結果の取得</title>

        <para>
            ステートメントオブジェクトのメソッドをコールすることで、
            SQL 文の結果セットから行を取得することができます。
            SELECT、SHOW、DESCRIBE そして EXPLAIN
            などのステートメントが結果セットを返します。
            INSERT、UPDATE そして DELETE などのステートメントは結果セットを返しません。
            後者のような SQL 文も <classname>Zend_Db_Statement</classname> で実行できますが、
            その結果から行を取得するメソッドをコールすることはできません。
        </para>

        <sect3 id="zend.db.statement.fetching.fetch">

            <title>結果セットからの単一の行の取得</title>

            <para>
                結果セットから単一の行を取得するには、ステートメントオブジェクトの
                <code>fetch()</code> メソッドを使用します。
                このメソッドの三つの引数は、いずれも省略可能です。
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        最初の引数は
                        <emphasis role="strong">取得形式</emphasis>
                        を指定します。これは、返り値の構造を決めるものです。
                        ここで指定できる値と対応する返り値については
                        <xref linkend="zend.db.adapter.select.fetch-mode" />
                        を参照ください。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        二番目の引数で指定するのは、
                        <emphasis role="strong">カーソルの種類</emphasis>
                        です。デフォルトは Zend_Db::FETCH_ORI_NEXT
                        で、<code>fetch()</code> をコールするたびに
                        RDBMS が返す順で次の行を返すというものです。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        三番目の引数で指定するのは
                        <emphasis role="strong">オフセット</emphasis> です。
                        カーソルの種類が Zend_Db::FETCH_ORI_ABS の場合、
                        これは結果セットの中の何行目を返すのかを表します。
                        カーソルの種類が Zend_Db::FETCH_ORI_REL の場合、
                        これは直前に <code>fetch()</code>
                        をコールした際の位置からの相対位置を表します。
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                すでに結果セットのすべての行が取得済みである場合は
                <code>fetch()</code> は <code>false</code> を返します。
            </para>

            <example id="zend.db.statement.fetching.fetch.example">
                <title>ループ内での fetch() の使用</title>
                <programlisting role="php"><![CDATA[
$stmt = $db->query('SELECT * FROM bugs');

while ($row = $stmt->fetch()) {
    echo $row['bug_description'];
}
]]>
                </programlisting>
            </example>

            <para>
                <ulink url="http://www.php.net/PDOStatement-fetch">PDOStatement::fetch()</ulink>
                のマニュアルも参照ください。
            </para>

        </sect3>

        <sect3 id="zend.db.statement.fetching.fetchall">

            <title>結果セット全体の取得</title>

            <para>
                結果セットのすべての行を一度に取得するには、
                <code>fetchAll()</code> メソッドを使用します。
                これは、ループ内で <code>fetch()</code>
                メソッドを繰り返し使用してすべての行を配列に格納するのと同じことです。
                <code>fetchAll()</code> メソッドにはふたつの引数を指定できます。
                最初の引数は、先ほど説明したのと同じ取得形式です。
                二番目の引数は、返すカラム番号を指定します。これは最初の引数が
                Zend_Db::FETCH_COLUMN である場合に使用します。
            </para>

            <example id="zend.db.statement.fetching.fetchall.example">
                <title>fetchAll() の使用法</title>
                <programlisting role="php"><![CDATA[
$stmt = $db->query('SELECT * FROM bugs');

$rows = $stmt->fetchAll();

echo $rows[0]['bug_description'];
]]>
                </programlisting>
            </example>

            <para>
                <ulink url="http://www.php.net/PDOStatement-fetchAll">PDOStatement::fetchAll()</ulink>
                のマニュアルも参照ください。
            </para>

        </sect3>

        <sect3 id="zend.db.statement.fetching.fetch-mode">

            <title>取得形式の変更</title>

            <para>
                デフォルトでは、ステートメントオブジェクトが結果セットの行を返す形式は連想配列で、
                カラム名とそのカラムの値を関連付けたものとなります。
                結果を別の形式で返すように指定する方法は、アダプタクラスの場合と同じです。
                ステートメントオブジェクトの <code>setFetchMode()</code>
                メソッドで、取得形式を指定します。指定できる値は、Zend_Db クラスの定数
                FETCH_ASSOC、FETCH_NUM、FETCH_BOTH、FETCH_COLUMN そして FETCH_OBJ です。
                これらについての詳細は
                <xref linkend="zend.db.adapter.select.fetch-mode" /> を参照ください。
                これを指定すると、それ以降の <code>fetch()</code> メソッドや
                <code>fetchAll()</code> メソッドでその形式を使用するようになります。
            </para>

            <example id="zend.db.statement.fetching.fetch-mode.example">
                <title>取得形式の設定</title>
                <programlisting role="php"><![CDATA[
$stmt = $db->query('SELECT * FROM bugs');

$stmt->setFetchMode(Zend_Db::FETCH_NUM);

$rows = $stmt->fetchAll();

echo $rows[0][0];
]]>
                </programlisting>
            </example>

            <para>
                <ulink url="http://www.php.net/PDOStatement-setFetchMode">PDOStatement::setFetchMode()</ulink>
                のマニュアルも参照ください。
            </para>

        </sect3>

        <sect3 id="zend.db.statement.fetching.fetchcolumn">

            <title>結果セットからの単一のカラムの取得</title>

            <para>
                結果セットの次の行から単一のカラムの値を取得するには
                <code>fetchColumn()</code> を使用します。
                取得するカラムの位置を表すインデックスを引数で指定します。
                省略した場合のデフォルトは 0 となります。このメソッドは、
                スカラー値を返します。もし結果セットのすべての行が既に取得済みである場合は
                <code>false</code> を返します。
            </para>

            <para>
                このメソッドの動作は、アダプタクラスの
                <code>fetchCol()</code> メソッドとは異なることに注意しましょう。
                ステートメントクラスの <code>fetchColumn()</code> メソッドは、
                単一の行の単一の値を返します。アダプタの
                <code>fetchCol()</code> メソッドは、値の配列を返します。
                これは、結果セットのすべての行の、最初のカラムの値をまとめたものです。
            </para>

            <example id="zend.db.statement.fetching.fetchcolumn.example">
                <title>fetchColumn() の使用法</title>
                <programlisting role="php"><![CDATA[
$stmt = $db->query('SELECT bug_id, bug_description, bug_status FROM bugs');

$bug_status = $stmt->fetchColumn(2);
]]>
                </programlisting>
            </example>

            <para>
                <ulink url="http://www.php.net/PDOStatement-fetchColumn">PDOStatement::fetchColumn()</ulink>
                のマニュアルも参照ください。
            </para>

        </sect3>

        <sect3 id="zend.db.statement.fetching.fetchobject">

            <title>オブジェクト形式での行の取得</title>

            <para>
                結果セットの行をオブジェクトとして取得するには
                <code>fetchObject()</code> を使用します。このメソッドの引数は二つで、
                いずれも省略可能です。最初の引数には、返り値のオブジェクトのクラス名を指定します。
                デフォルトは 'stdClass' です。二番目の引数には配列を指定します。
                これは、最初の引数で指定したクラスのコンストラクタに渡す引数となります。
            </para>

            <example id="zend.db.statement.fetching.fetchobject.example">
                <title>fetchObject() の使用法</title>
                <programlisting role="php"><![CDATA[
$stmt = $db->query('SELECT bug_id, bug_description, bug_status FROM bugs');

$obj = $stmt->fetchObject();

echo $obj->bug_description;
]]>
                </programlisting>
            </example>

            <para>
                <ulink url="http://www.php.net/PDOStatement-fetchObject">PDOStatement::fetchObject()</ulink>
                のマニュアルも参照ください。
            </para>

        </sect3>

    </sect2>

    <!--
      @todo: binding parameters is not working yet.

    <sect2 id="zend.db.statement.binding-param">

        <title>Binding PHP Variables to Parameters</title>

        <para>
        </para>

        <example id="zend.db.statement.binding-param.example">
            <title>Binding parameters from PHP variables</title>
            <programlisting role="php"><![CDATA[
]]>
            </programlisting>
        </example>

        <para>
            See also <ulink url="http://www.php.net/PDOStatement-bindParam">PDOStatement::bindParam()</ulink>.
        </para>

    </sect2>
    -->

    <!--
      @todo: binding columns is not working yet.
    <sect2 id="zend.db.statement.binding-column">

        <title>Binding PHP Variables to Query Results</title>

        <para>
        </para>

        <example id="zend.db.statement.binding-column.example">
            <title>Binding results to PHP variables</title>
            <programlisting role="php"><![CDATA[
]]>
            </programlisting>
        </example>

        <para>
            See also <ulink url="http://www.php.net/PDOStatement-bindColumn">PDOStatement::bindColumn()</ulink>.
        </para>

    </sect2>
    -->

</sect1>