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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.db.statement">
    <title>Zend_Db_Statement</title>

    <para>
        In addition to convenient methods such as <methodname>fetchAll()</methodname> and
        <methodname>insert()</methodname> documented in <link
            linkend="zend.db.adapter">Zend_Db_Adapter</link>, you can use a statement object to gain
        more options for running queries and fetching result sets. This section describes how to get
        an instance of a statement object, and how to use its methods.
    </para>

    <para>
        <classname>Zend_Db_Statement</classname> is based on the PDOStatement object in the
        <ulink url="http://www.php.net/pdo">PHP Data Objects</ulink> extension.
    </para>

    <sect2 id="zend.db.statement.creating">
        <title>Creating a Statement</title>

        <para>
            Typically, a statement object is returned by the
            <methodname>query()</methodname> method of the database Adapter class.
            This method is a general way to prepare any <acronym>SQL</acronym> statement.
            The first argument is a string containing an <acronym>SQL</acronym> statement.
            The optional second argument is an array of values to bind
            to parameter placeholders in the <acronym>SQL</acronym> string.
        </para>

        <example id="zend.db.statement.creating.example1">
            <title>Creating a SQL statement object with query()</title>

            <programlisting language="php"><![CDATA[
$stmt = $db->query(
            'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?',
            array('goofy', 'FIXED')
        );
]]></programlisting>
        </example>

        <para>
            The statement object corresponds to a <acronym>SQL</acronym> statement that has been
            prepared, and executed once with the bind-values specified.
            If the statement was a <acronym>SELECT</acronym> query or other type of statement
            that returns a result set, it is now ready to fetch results.
        </para>

        <para>
            You can create a statement with its constructor, but this is less
            typical usage. There is no factory method to create this object,
            so you need to load the specific statement class and call its
            constructor. Pass the Adapter object as the first argument, and
            a string containing an <acronym>SQL</acronym> statement as the second argument.
            The statement is prepared, but not executed.
        </para>

        <example id="zend.db.statement.creating.example2">
            <title>Using a SQL statement constructor</title>

            <programlisting language="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>Executing a Statement</title>

        <para>
            You need to execute a statement object if you create it using its
            constructor, or if you want to execute the same statement multiple
            times. Use the <methodname>execute()</methodname> method of the statement
            object. The single argument is an array of value to bind to
            parameter placeholders in the statement.
        </para>

        <para>
            If you use <emphasis>positional parameters</emphasis>, or those
            that are marked with a question mark symbol ('<emphasis>?</emphasis>'), pass
            the bind values in a plain array.
        </para>

        <example id="zend.db.statement.executing.example1">
            <title>Executing a statement with positional parameters</title>

            <programlisting language="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>
            If you use <emphasis>named parameters</emphasis>, or those that are
            indicated by a string identifier preceded by a colon character
            ('<emphasis>:</emphasis>'), pass the bind values in an associative array.
            The keys of this array should match the parameter names.
        </para>

        <example id="zend.db.statement.executing.example2">
            <title>Executing a statement with named parameters</title>

            <programlisting language="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>
            <acronym>PDO</acronym> statements support both positional parameters and named
            parameters, but not both types in a single <acronym>SQL</acronym> statement. Some of
            the <classname>Zend_Db_Statement</classname> classes for non-PDO extensions may support
            only one type of parameter or the other.
        </para>
    </sect2>

    <sect2 id="zend.db.statement.fetching">
        <title>Fetching Results from a SELECT Statement</title>

        <para>
            You can call methods on the statement object to retrieve rows from
            <acronym>SQL</acronym> statements that produce result set. <acronym>SELECT</acronym>,
            <acronym>SHOW</acronym>, <acronym>DESCRIBE</acronym> and <acronym>EXPLAIN</acronym> are
            examples of statements that produce a result set. <acronym>INSERT</acronym>,
            <acronym>UPDATE</acronym>, and <acronym>DELETE</acronym> are examples of statements that
            don't produce a result set. You can execute the latter <acronym>SQL</acronym> statements
            using <classname>Zend_Db_Statement</classname>, but you cannot call methods to fetch
            rows of results from them.
        </para>

        <sect3 id="zend.db.statement.fetching.fetch">
            <title>Fetching a Single Row from a Result Set</title>

            <para>
                To retrieve one row from the result set, use the
                <methodname>fetch()</methodname> method of the statement object.
                All three arguments of this method are optional:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>Fetch style</emphasis> is the
                        first argument. This controls the structure in which
                        the row is returned.
                        See <link linkend="zend.db.adapter.select.fetch-mode">this chapter</link>
                        for a description of the valid values and the
                        corresponding data formats.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Cursor orientation</emphasis>
                        is the second argument. The default is
                        <constant>Zend_Db::FETCH_ORI_NEXT</constant>, which simply means that each
                        call to <methodname>fetch()</methodname> returns the next row in
                        the result set, in the order returned by the <acronym>RDBMS</acronym>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Offset</emphasis> is the third
                        argument.
                        If the cursor orientation is <constant>Zend_Db::FETCH_ORI_ABS</constant>,
                        then the offset number is the ordinal number of the row to return.
                        If the cursor orientation is <constant>Zend_Db::FETCH_ORI_REL</constant>,
                        then the offset number is relative to the cursor
                        position before <methodname>fetch()</methodname> was called.
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                <methodname>fetch()</methodname> returns <constant>FALSE</constant> if all rows of
                the result set have been fetched.
            </para>

            <example id="zend.db.statement.fetching.fetch.example">
                <title>Using fetch() in a loop</title>

                <programlisting language="php"><![CDATA[
$stmt = $db->query('SELECT * FROM bugs');

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

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

        <sect3 id="zend.db.statement.fetching.fetchall">
            <title>Fetching a Complete Result Set</title>

            <para>
                To retrieve all the rows of the result set in one step, use the
                <methodname>fetchAll()</methodname> method. This is equivalent to calling
                the <methodname>fetch()</methodname> method in a loop and returning all
                the rows in an array. The <methodname>fetchAll()</methodname> method accepts
                two arguments. The first is the fetch style, as described above,
                and the second indicates the number of the column to return,
                when the fetch style is <constant>Zend_Db::FETCH_COLUMN</constant>.
            </para>

            <example id="zend.db.statement.fetching.fetchall.example">
                <title>Using fetchAll()</title>

                <programlisting language="php"><![CDATA[
$stmt = $db->query('SELECT * FROM bugs');

$rows = $stmt->fetchAll();

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

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

        <sect3 id="zend.db.statement.fetching.fetch-mode">
            <title>Changing the Fetch Mode</title>

            <para>
                By default, the statement object returns rows of the result set
                as associative arrays, mapping column names to column values.
                You can specify a different format for the statement class to
                return rows, just as you can in the Adapter class. You can use
                the <methodname>setFetchMode()</methodname> method of the statement object
                to specify the fetch mode. Specify the fetch mode using
                <classname>Zend_Db</classname> class constants <constant>FETCH_ASSOC</constant>,
                <constant>FETCH_NUM</constant>, <constant>FETCH_BOTH</constant>,
                <constant>FETCH_COLUMN</constant>, and <constant>FETCH_OBJ</constant>.
                See <link linkend="zend.db.adapter.select.fetch-mode">this chapter</link>
                for more information on these modes. Subsequent calls to the statement methods
                <methodname>fetch()</methodname> or <methodname>fetchAll()</methodname> use the
                fetch mode that you specify.
            </para>

            <example id="zend.db.statement.fetching.fetch-mode.example">
                <title>Setting the fetch mode</title>

                <programlisting language="php"><![CDATA[
$stmt = $db->query('SELECT * FROM bugs');

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

$rows = $stmt->fetchAll();

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

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

        <sect3 id="zend.db.statement.fetching.fetchcolumn">
            <title>Fetching a Single Column from a Result Set</title>

            <para>
                To return a single column from the next row of the result set,
                use <methodname>fetchColumn()</methodname>. The optional argument is the
                integer index of the column, and it defaults to 0. This method
                returns a scalar value, or <constant>FALSE</constant> if all rows of
                the result set have been fetched.
            </para>

            <para>
                Note this method operates differently than the
                <methodname>fetchCol()</methodname> method of the Adapter class.
                The <methodname>fetchColumn()</methodname> method of a statement returns a
                single value from one row.
                The <methodname>fetchCol()</methodname> method of an adapter returns an
                array of values, taken from the first column of all rows of the
                result set.
            </para>

            <example id="zend.db.statement.fetching.fetchcolumn.example">
                <title>Using fetchColumn()</title>

                <programlisting language="php"><![CDATA[
$stmt = $db->query('SELECT bug_id, bug_description, bug_status FROM bugs');

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

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

        <sect3 id="zend.db.statement.fetching.fetchobject">
            <title>Fetching a Row as an Object</title>

            <para>
                To retrieve a row from the result set structured as an object,
                use the <methodname>fetchObject()</methodname>. This method takes two
                optional arguments. The first argument is a string that names
                the class name of the object to return; the default is
                'stdClass'. The second argument is an array of values that
                will be passed to the constructor of that class.
            </para>

            <example id="zend.db.statement.fetching.fetchobject.example">
                <title>Using fetchObject()</title>

                <programlisting language="php"><![CDATA[
$stmt = $db->query('SELECT bug_id, bug_description, bug_status FROM bugs');

$obj = $stmt->fetchObject();

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

            <para>
                See also <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 language="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 language="php"><![CDATA[
]]></programlisting>
        </example>

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

    </sect2>
    -->
</sect1>