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

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

    <para>
        En plus des méthodes telles que <methodname>fetchAll()</methodname> et <methodname>insert()</methodname>
        documentée dans <xref linkend="zend.db.adapter" />, vous pouvez utiliser un objet statement
        pour l'analyser de manière plus complète et récupérer vos résultats. Cette section décrit la
        marche à suivre pour obtenir un statement et utiliser ses méthodes propres.
    </para>

    <para>
        Zend_Db_Statement est basé sur l'objet PDOStatement dans l'extension <acronym>PHP</acronym> <ulink
        url="http://www.php.net/pdo">PHP Data Objects (PDO)</ulink>.
    </para>

    <sect2 id="zend.db.statement.creating">
        <title>Créer un statement</title>

        <para>
            Cet objet est typiquement retourné par la méthode <methodname>query()</methodname> de votre
            objet adaptateur de base de données. Cette méthode prépare un statement <acronym>SQL</acronym> : le premier
            argument est une chaîne représentant la requête préparée, le second, un tableau de
            paramètres liés.
        </para>

        <example id="zend.db.statement.creating.example1">
            <title>Création d'un objet statement avec query()</title>

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

        <para>
            L'objet statement représente un statement <acronym>SQL</acronym> qui a été préparé, et exécuté une
            fois avec les paramètres de liaison ("bind") spécifiés. S'il s'agissait d'une requête
            SELECT par exemple, alors les résultats sont prêts à être récupérés.
        </para>

        <para>
            Vous pouvez créer un statement avec son constructeur, mais c'est assez peu usuel.
            Passez alors l'objet adaptateur en premier argument, et la chaîne représentant la
            requête en second. Un fois construit, le statement est préparé automatiquement, mais pas
            exécuté.
        </para>

        <example id="zend.db.statement.creating.example2">
            <title>Utilisation du constructeur de statement</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>Exécuter un statement</title>

        <para>
            Vous aurez besoin d'exécuter un statement si vous l'avez crée explicitement avec
            son constructeur. Utilisez sa méthode <methodname>execute()</methodname> pour ceci. Le seul argument
            que cette méthode accepte est le tableau de "binds" (paramètres préparés).
        </para>

        <para>
            Si vous utilisez les <emphasis>paramètres positionnés</emphasis>, ceux utilisés
            avec le point d'interrogation (<code>?</code>), passez simplement les valeurs dans le
            tableau.
        </para>

        <example id="zend.db.statement.executing.example1">
            <title>Exécuter un statement avec des paramètres positionnés</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 vous utilisez les <emphasis>paramètres nommés</emphasis>, ceux définis avec un
            identifiant chaîne de caractère précédée d'un (<code>:</code>), passez les valeurs liées
            sous forme de tableau associatif.
        </para>

        <example id="zend.db.statement.executing.example2">
            <title>Exécution d'un statement avec paramètres nommés</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>
            Les statements <acronym>PDO</acronym> acceptent les paramètres positionnés, ou nommés, mais pas les
            deux types en même temps. Certaines classes Zend_Db_Statement pour les extensions non
            <acronym>PDO</acronym> peuvent ne supporter qu'un seul de ces types.
        </para>
    </sect2>

    <sect2 id="zend.db.statement.fetching">
        <title>Récupérer des résultats depuis un statement SELECT</title>

        <para>
            Vous disposez de méthodes sur l'objet statement lorsque celui-ci a été exécuté sur
            une requête <acronym>SQL</acronym> de type SELECT, SHOW, DESCRIBE ou EXPLAIN (qui produisent des
            résultats). Aussi, INSERT, UPDATE et DELETE sont des exemples de requêtes ne produisant
            pas de résultats. Vous pouvez donc les exécuter avec Zend_Db_Statement, mais vous ne
            pourrez pas appeler les méthodes de récupération de résultats.
        </para>

        <sect3 id="zend.db.statement.fetching.fetch">
            <title>Récupérer un enregistrement unique depuis un statement</title>

            <para>
                La méthode <methodname>fetch()</methodname> permet de ne récupérer qu'un seul résultat
                dans le statement précédemment exécuté. Trois paramètres sont disponibles pour cette
                méthode, tous optionnels&#160;:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>Fetch style</emphasis> en premier, permet de spécifier le
                        mode de capture du résultat. C'est la structure dans laquelle celui-ci vous
                        sera retourné. Voyez <xref linkend="zend.db.adapter.select.fetch-mode" />
                        pour une description des valeurs valides et de la forme des résultats alors
                        renvoyés.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Cursor orientation</emphasis> est le second paramètre. Par
                        défaut il vaut <classname>Zend_Db::FETCH_ORI_NEXT</classname>, ce qui
                        signifie que chaque appel futur à <methodname>fetch()</methodname> retourne
                        l'enregistrement suivant.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Offset</emphasis>, en troisième paramètre. Si le paramètre
                        "cursor orientation" est réglé sur
                        <classname>Zend_Db::FETCH_ORI_ABS</classname>, alors le numéro d'offset est
                        le numéro du résultat à retourner, dans le statement. Si c'est
                        <classname>Zend_Db::FETCH_ORI_REL</classname>, le numéro d'offset est
                        relatif à la position du curseur avant l'appel à
                        <methodname>fetch()</methodname>.
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                <methodname>fetch()</methodname> retourne <constant>FALSE</constant> si il n'y a plus de résultats
                restants dans le statement.
            </para>

            <example id="zend.db.statement.fetching.fetch.example">
                <title>Utiliser fetch() dans une boucle</title>

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

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

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

        <sect3 id="zend.db.statement.fetching.fetchall">
            <title>Récupérer un jeu de résultat complet</title>

            <para>
                Pour récupérer tous les résultats d'un statement, utilisez
                <methodname>fetchAll()</methodname>. Ceci est équivalent à appeler <methodname>fetch()</methodname> dans un
                boucle et retourner tous les résultats dans un tableau. La méthode
                <methodname>fetchAll()</methodname> accepte deux paramètres. Le premier est le mode de capture
                (fetch style), le deuxième est le numéro de la colonne à retourner, si
                Zend_Db::FETCH_COLUMN est utilisé.
            </para>

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

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

$rows = $stmt->fetchAll();

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

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

        <sect3 id="zend.db.statement.fetching.fetch-mode">
            <title>Changer le mode de capture (Fetch Mode)</title>

            <para>
                Par défaut l'objet statement retourne les colonnes du jeu de résultat en tant
                que tableau associatif, en faisant correspondre les noms des colonne et leur valeur.
                Vous pouvez cependant spécifier un format différent, comme il est possible de faire
                avec la classe de l'adaptateur. La méthode <methodname>setFetchMode()</methodname> permet ceci.
                Indiquez un mode de capture en utilisant les constantes de la classe Zend_Db :
                FETCH_ASSOC, FETCH_NUM, FETCH_BOTH, FETCH_COLUMN, et FETCH_OBJ. Voyez <xref
                linkend="zend.db.adapter.select.fetch-mode" /> pour plus d'informations sur ces
                modes de capture. Les appels suivants à <methodname>fetch()</methodname> ou
                <methodname>fetchAll()</methodname> utiliseront le mode spécifié auparavant.
            </para>

            <example id="zend.db.statement.fetching.fetch-mode.example">
                <title>Paramétrer le mode de capture (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>
                Voyez aussi <ulink
                url="http://www.php.net/PDOStatement-setFetchMode">PDOStatement::setFetchMode()</ulink>.
            </para>
        </sect3>

        <sect3 id="zend.db.statement.fetching.fetchcolumn">
            <title>Récupérer une colonne simple depuis un statement exécuté</title>

            <para>
                Pour retourner une colonne de résultat depuis un statement, utilisez la
                méthode <methodname>fetchColumn()</methodname>. Le paramètre optionnel est un entier
                représentant l'index de la colonne désirée, par défaut zéro. Cette méthode retourne
                un type scalaire, ou <constant>FALSE</constant> s'il n'y a plus de résultats dans le
                statement.
            </para>

            <para>
                Notez que cette méthode se comporte différemment de <methodname>fetchCol()</methodname> de
                l'adaptateur. La méthode <methodname>fetchColumn()</methodname> du statement retourne une seule
                valeur d'un seul résultat. <methodname>fetchCol()</methodname> de l'adaptateur retourne un
                tableau de valeurs issues de la première colonne du jeu résultat.
            </para>

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

                <programlisting language="php"><![CDATA[
$sql = 'SELECT bug_id, bug_description, bug_status FROM bugs';

$stmt = $db->query($sql);

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

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

        <sect3 id="zend.db.statement.fetching.fetchobject">
            <title>Récupérer un résultat (Row) sous forme d'objet</title>

            <para>
                Pour récupérer une ligne de résultat en tant qu'objet, depuis un statement
                exécuté, utilisez la méthode <methodname>fetchObject()</methodname>. Celle-ci prend deux
                paramètres optionnels. Le premier est une chaîne indiquant le nom de la classe que
                l'on souhaite se voir retourner, par défaut il s'agit de "<code>stdClass</code>". Le
                deuxième paramètre est un tableau de paramètres qui sera passé au constructeur de
                cette classe.
            </para>

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

                <programlisting language="php"><![CDATA[
$sql = 'SELECT bug_id, bug_description, bug_status FROM bugs';

$stmt = $db->query($sql);

$obj = $stmt->fetchObject();

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

            <para>
                Voyez aussi <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>