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

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

    <title>Zend_Db_Statement</title>

    <para> Además de algunos métodos convenientes tales como
            <methodname>fetchAll()</methodname> e
            <methodname>insert()</methodname> documentados en <xref
            linkend="zend.db.adapter"/> , puede usarse un objeto de declaración
        para obtener más opciones al ejecutar consultas y devolver conjuntos de
        resultados. Esta sección describe cómo obtener una instancia de un
        objeto de declaración y cómo usar sus métodos. </para>

    <para>
        <classname>Zend_Db_Statement</classname> está basado en el objeto
        PDOStatement en la extensión <ulink url="http://www.php.net/pdo">PHP
            Data Objects</ulink> . </para>

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

        <title>Creando una Declaración</title>

        <para> Típicamente, un objeto de declaración statement es devuelto por
            el método <methodname>query()</methodname> de la clase de Adaptador
            de la base de datos. Este método es un modo general de preparar una
            declaración <acronym>SQL</acronym> . El primer parámetro es un
            string conteniendo la declaración <acronym>SQL</acronym> . El
            segundo parámetro (opcional) es un array de valores para vincular
            posiciones de parámetros en el string <acronym>SQL</acronym> . </para>

        <example id="zend.db.statement.creating.example1">
            <title>Crear un objeto de declaración SQL con query()</title>
            <programlisting language="php"><![CDATA[
$stmt = $db->query(
            'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?',
            array('goofy', 'FIXED')
        );
]]></programlisting>
        </example>

        <para> El objeto de declaración corresponde a una declaración
                <acronym>SQL</acronym> que ha sido preparada y ejecutada una vez
            con valores vinculados especificados. Si la declaración fue una
            consulta SELECT u otro tipo de declaración que devuelve un conjunto
            de resultados, ahora estará lista para extraer resultados. </para>

        <para> Puede crear una declaración con su constructor, pero éste es un
            uso menos típico. No hay un método factory para crear el objeto, así
            que es necesario cargar una clase de declaración específica y llamar
            a su constructor. Pase el objeto Adaptador como el primer parámetro,
            y un string conteniendo la declaración <acronym>SQL</acronym> como
            el segundo parámetro. La declaración es preparada pero no ejecutada. </para>

        <example id="zend.db.statement.creating.example2">
            <title>Usando un constructor de declaración SQL</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>Ejecutando la declaración</title>

        <para> Necesita ejecutar un objeto de declaración si lo crea con el
            constructor, o si desea ejecutar la misma declaración varias veces.
            Use el método <methodname>execute()</methodname> del mismo objeto de
            declaración. El único parámetro es un array de valores a vincular a
            posiciones de parámetros en la declaración. </para>

        <para> Si usa <emphasis>parámetros posicionales</emphasis> , o los que
            están marcados por un signo de interrogación (
                <emphasis>?</emphasis> ), pase los valores de vinculación en un
            array plano. </para>

        <example id="zend.db.statement.executing.example1">
            <title>Ejecutar una declaración con parámetros posicionales</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> Si usa <emphasis>parámetros nombrados</emphasis> , o los que son
            indicados por un string identificador precedido por un caracter de
            dos puntos ( <emphasis>:</emphasis> ), pase el valor en un array
            asociativo. Las claves de este array deben coincidir con el nombre
            de los parámetros. </para>

        <example id="zend.db.statement.executing.example2">
            <title>Ejecutando una declaración con parámetros nombrados</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> Las declaraciones <acronym>PDO</acronym> soportan tanto
            parámetros posicionales como parámetros nombrados, pero no ambos
            tipos en la misma declaración <acronym>SQL</acronym> . Algunas
            clases <classname>Zend_Db_Statement</classname> para extensiones
            no-PDO soportan solo un tipo de parámetro o el otro. </para>

    </sect2>

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

        <title> Extrayendo Resultados de una declaración SELECT </title>

        <para> Puede llamar a métodos del objeto de declaración para obtener
            filas desde declaraciones <acronym>SQL</acronym> que producen
            conjuntos de resultados. SELECT, SHOW, DESCRIBE y EXPLAIN son
            ejemplos de declaraciones que producen un conjunto de resultados.
            INSERT, UPDATE, and DELETE son ejemplo de declaraciones que no
            producen un conjunto de resultados. Puede ejecutar las últimas
            declaraciones de <acronym>SQL</acronym> usando
                <classname>Zend_Db_Statement</classname> , pero no puede llamar
            a los métodos que extraen filas de resultados desde éste. </para>

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

            <title>Extrayendo una Fila Simple desde un Conjunto de
                Resultados</title>

            <para> Para extraer una fila desde el conjunto de resultados, use el
                método <methodname>fetch()</methodname> del objeto de
                declaración. Los tres parámetros de este método son opcionales: </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>Estilo de Extracción</emphasis> es el primer
                        parámetro. Éste controla la estructura en la que será
                        devuelta la fila. Vea <xref
                            linkend="zend.db.adapter.select.fetch-mode"/> para
                        la descripción de un valor válido los correspondientes
                        formatos de datos. </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>Orientación del Cursor</emphasis> es el
                        segundo parámetro. Por omisión es
                        Zend_Db::FETCH_ORI_NEXT, lo cual simplemente significa
                        que cada llamada a <methodname>fetch()</methodname>
                        devuelve la siguiente fila del resultado, en el orden
                        devuelto por el <acronym>RDBMS</acronym> . </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>Compensación</emphasis> es el tercer
                        parámetro. Si la orientación del cursor es
                        Zend_Db::FETCH_ORI_ABS, entonces el offset es el número
                        ordinal de las filas que devolver. Si la orientación del
                        cursor es Zend_Db::FETCH_ORI_REL, entonces el offset es
                        relativo a la posición del cursor antes de que
                            <methodname>fetch()</methodname> fuera llamado.
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                <methodname>fetch()</methodname> devuelve
                    <constant>FALSE</constant> si todas las filas del conjunto
                de resultados han sido extraídas. </para>

            <example id="zend.db.statement.fetching.fetch.example">
                <title>Usando fetch() en un bucle</title>
                <programlisting language="php"><![CDATA[
$stmt = $db->query('SELECT * FROM bugs');

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

            <para> Vea también <ulink
                    url="http://www.php.net/PDOStatement-fetch"
                    >PDOStatement::fetch()</ulink> . </para>

        </sect3>

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

            <title>Extrayendo un Conjunto de Resultados completo</title>

            <para> Para extraer todas las filas de un resultado en un solo paso,
                use el método <methodname>fetchAll()</methodname> . Esto es
                equivalente a llamar al método <methodname>fetch()</methodname>
                en un bucle devolviendo todas las filas en una array. El método
                    <methodname>fetchAll()</methodname> acepta 2 parámetros. El
                primero es el estilo de extracción, descrito anteriormente, y el
                segundo indica el número de la columa que devolver, cuando el
                estilo de extracción es Zend_Db::FETCH_COLUMN. </para>

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

$rows = $stmt->fetchAll();

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

            <para> Vea también <ulink
                    url="http://www.php.net/PDOStatement-fetchAll"
                    >PDOStatement::fetchAll()</ulink> . </para>

        </sect3>

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

            <title>Cambiando el Modo de extracción</title>

            <para> Por defecto, el objeto de declaración devuelve filas de un
                conjunto de resultados como array asociativo, mapeando los
                nombres de columnas a los valores de la columna. Se puede
                especificar un formato diferente para que la clase de
                declaración devuelva las filas, tal como se puede con la clase
                Adaptadora. Puede usar él método
                    <methodname>setFetchMode()</methodname> para establecer el
                modo de extracción. Especifique el modo de extracción usando las
                constantes de la clase Zend_Db: FETCH_ASSOC, FETCH_NUM,
                FETCH_BOTH, FETCH_COLUMN, and FETCH_OBJ. Vea <xref
                    linkend="zend.db.adapter.select.fetch-mode"/> para más
                información de estos modos. Llamadas subsiguientes a los métodos
                de la declaración <methodname>fetch()</methodname> o
                    <methodname>fetchAll()</methodname> usan el modo de
                extracción especificado. </para>

            <example id="zend.db.statement.fetching.fetch-mode.example">
                <title>Configurando un modo de extracción</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> Vea también <ulink
                    url="http://www.php.net/PDOStatement-setFetchMode"
                    >PDOStatement::setFetchMode()</ulink> . </para>

        </sect3>

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

            <title>Extrayendo una Única Columna desde un Conjunto de
                Resultados</title>

            <para> Para devolver una única columna de la siguiente fila del
                conjunto de resultados, use
                    <methodname>fetchColumn()</methodname> . El parámetro
                opcional es el índice de la columna (integer), y por defecto es
                0. Este método devuelve un valor escalar, o
                    <constant>FALSE</constant> si todas las filas del conjunto
                de resultados han sido extraídas. </para>

            <para> Note que este método opera diferente que el método
                    <methodname>fetchCol()</methodname> de la clase Adaptadora.
                El método <methodname>fetchColumn()</methodname> de una
                declaración devuelve un único valor desde una fila. El método
                    <methodname>fetchCol()</methodname> de un adaptador devuelve
                un array de valores, tomados desde la primera columa de todas
                las del conjunto de resultados. </para>

            <example id="zend.db.statement.fetching.fetchcolumn.example">
                <title>Usando 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> Vea también <ulink
                    url="http://www.php.net/PDOStatement-fetchColumn"
                    >PDOStatement::fetchColumn()</ulink> . </para>

        </sect3>

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

            <title>Extrayendo una Fila como un Objeto</title>

            <para> Para extraer una fila desde un conjunto de resultados
                estructurado como un Objeto, use el método
                    <methodname>fetchObject()</methodname> . Este método tiene 2
                parámetros opcionales. El primer parámetro es un string con el
                nombre de la clase del objeto que devolver; por defecto será
                'stdClass'. El segundo parámetro es un array de valores que será
                pasado al constructor de la clase. </para>

            <example id="zend.db.statement.fetching.fetchobject.example">
                <title>Usando 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> Vea también <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[
        <?php
        ]]></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[
        <?php
        ]]></programlisting>
        </example> <para> See also <ulink
        url="http://www.php.net/PDOStatement-bindColumn">PDOStatement::bindColumn()</ulink>. </para>

        </sect2>
    -->

</sect1>