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

<sect1 id="zend.db.statement">

    <title>Zend_Db_Statement</title>

    <para>
        Además de algunos métodos convenientes tales como
        <code>fetchAll()</code> e <code>insert()</code> 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>
        Zend_Db_Statement 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 <code>query()</code> de la clase de Adaptador de la base de
            datos.
            Este método es un modo general de preparar una declaración SQL.
            El primer parámetro es un string conteniendo la declaración SQL.
            El segundo parámetro (opcional) es un array de valores para
            vincular posiciones de parámetros en el string SQL.
        </para>

        <example id="zend.db.statement.creating.example1">
            <title>Crear un objeto de declaración SQL con query()</title>
            <programlisting role="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 SQL 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 SQL 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 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>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 <code>execute()</code> 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 (<code>?</code>), 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 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>
            Si usa <emphasis>parámetros nombrados</emphasis>, o los que son
            indicados por un string identificador precedido por un caracter de
            dos puntos (<code>:</code>), 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 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>
            Las declaraciones PDO soportan tanto parámetros posicionales como
            parámetros nombrados, pero no ambos tipos en la misma declaración
            SQL. Algunas clases Zend_Db_Statement 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 <code>SELECT</code></title>

        <para>
            Puede llamar a métodos del objeto de declaración para obtener filas
            desde declaraciones SQL 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 SQL usando
            Zend_Db_Statement, 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 <code>fetch()</code> del objeto de declaración.
                Los tres parámetros de este método son opcionales:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis role="strong">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 role="strong">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 <code>fetch()</code> devuelve la
                        siguiente fila del resultado, en el orden devuelto por
                        el RDBMS.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis role="strong">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 <code>fetch()</code> fuera llamado.
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                <code>fetch()</code> devuelve <code>false</code> 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 role="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 <code>fetchAll()</code>. Esto es equivalente a
                llamar al método <code>fetch()</code> en un bucle devolviendo
                todas las filas en una array. El método <code>fetchAll()</code>
                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 role="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 <code>setFetchMode()</code>
                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
                <code>fetch()</code> o <code>fetchAll()</code> 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 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>
                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 <code>fetchColumn()</code>. El
                parámetro opcional es el índice de la columna (integer), y por
                defecto es 0. Este método devuelve un valor escalar, o
                <code>false</code> 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
                <code>fetchCol()</code> de la clase Adaptadora.
                El método <code>fetchColumn()</code> de una declaración devuelve
                un único valor desde una fila.
                El método <code>fetchCol()</code> 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 role="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
                <code>fetchObject()</code>.  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 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>
                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 role="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 role="php"><![CDATA[
<?php
]]>
            </programlisting>
        </example>

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

    </sect2>
    -->

</sect1>