repo_zf1/documentation/manual/de/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>
        Zusätzlich zu den herkömmlichen Methoden wie <methodname>fetchAll()</methodname> und
        <methodname>insert()</methodname>, beschrieben in <link
            linkend="zend.db.adapter">Zend_Db_Adapter</link>, kann auch ein Statement-Objekt
        verwendet werden, um zusätzliche Möglichkeiten beim Ausführen von Abfragen und holen von
        Ergebnissätzen zu erhalten. Dieser Abschnitt beschreibt wie eine Instanz eines
        Statement-Objekts erzeugt wird, und wie dessen Methoden verwendet werden.
    </para>

    <para>
        <classname>Zend_Db_Statement</classname> basiert auf dem PDOStatement
        Objekt aus der <ulink url="http://www.php.net/pdo">PHP Data Objects</ulink> Erweiterung.
    </para>

    <sect2 id="zend.db.statement.creating">
        <title>Erzeugung von Statement Objekten</title>

        <para>
            Normalerweise wird ein Statement Objekt von der <methodname>query()</methodname>
            Methode der Datenbank Adapterklasse zurück gegeben. Diese Methode ist der
            grundsätzliche Weg um ein beliebiges <acronym>SQL</acronym> Statement vor zu bereiten.
            Das erste Argument ist ein String, der das <acronym>SQL</acronym> Statement enthält. Das
            optionale zweite Argument ist ein Array von Werten, verknüpft mit Parameterplatzhaltern
            im <acronym>SQL</acronym> String.
        </para>

        <example id="zend.db.statement.creating.example1">
            <title>Erzeugung eines SQL Statement Objekts mit query()</title>

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

        <para>
            Das Statement Objekt entspricht einem <acronym>SQL</acronym> Statement welches
            vorbereitet und einmalig mit angegebenen verknüpften Werten ausgeführt wurde. War das
            Statement eine <acronym>SELECT</acronym> Abfrage, oder irgendein Statement welches ein
            Ergebnissatz zurück gibt, so ist es nun bereit um Ergebnisse zu holen.
        </para>

        <para>
            Ein Statement kann ebenfalls mit dem Konstruktor erzeugt werden, auch wenn dies eine
            weniger typische Nutzung ist. Es existiert jedoch keine factory Methode um das Objekt zu
            erzeugen, weßhalb die entsprechende Statementklasse geladen, und ihr Konstruktor
            aufgerufen werden muss. Als erstes Argument muss das Adapterobjekt übergeben werden und
            als zweites Argument ein String welcher das <acronym>SQL</acronym> Statement enthält.
            Das Statement ist dadurch vorbereitet, jedoch nicht Ausgeführt.
        </para>

        <example id="zend.db.statement.creating.example2">
            <title>Nutzung des SQL Statement Konstruktors</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>Ausführen eines Statements</title>

        <para>
            Ein Statement Objekt muss ausgeführt werden wenn es über den Konstruktor erzeugt wurde,
            oder kann, wenn es mehrere Male hintereinander ausgeführt werden soll. Dazu wird die
            <methodname>execute()</methodname> Methode des Statement Objekts verwendet. Das einzige
            Argument ist ein Array von Werten, welche mit Parameterplatzhaltern im Statement
            verknüpft werden.
        </para>

        <para>
            Wenn <emphasis>positionierte Parameter</emphasis>, oder solche, die mit dem Fragezeichen
            ('<emphasis>?</emphasis>') verwendet werden, muss ein einfaches Array übergeben werden.
        </para>

        <example id="zend.db.statement.executing.example1">
            <title>Ausführen eines Statements mit positionierten Parametern</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>
            Wenn <emphasis>benannte Parameter</emphasis>, oder solche die mit einem String und
            voranstehenden Doppelpunkt ('<emphasis>:</emphasis>') bezeichnet werden, verwendet
            werden, muss ein assoziatives Array übergeben werden. Die Schlüssel dieses Arrays müssen
            den Parameternamen entsprechen.
        </para>

        <example id="zend.db.statement.executing.example2">
            <title>Ausführen eines Statements mit benannten Parametern</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 unterstützen sowohl postionierte als auch benannte
            Parameter, jedoch nicht beide Typen in einem einzelnen <acronym>SQL</acronym> Statement.
            Einige der <classname>Zend_Db_Statement</classname> Klassen für nicht-PDO Erweiterungen
            könnten nur einen Typ von Parametern unterstützen.
        </para>
    </sect2>

    <sect2 id="zend.db.statement.fetching">
        <title>Holen von Ergebnissen eines SELECT Statements</title>

        <para>
            Es können Methoden des Statement Objekts aufgefufen werden um Zeilen von
            <acronym>SQL</acronym> Statements zu erhalten die Ergebnissätze erzeugen.
            <acronym>SELECT</acronym>, <acronym>SHOW</acronym>, <acronym>DESCRIBE</acronym> und
            <acronym>EXPLAIN</acronym> sind Beispiele von von Statements die Ergebnissätze erzeugen.
            <acronym>INSERT</acronym>, <acronym>UPDATE</acronym> und <acronym>DELETE</acronym> sind
            Beispiele von Statements die keine Ergebnissätze erzeugen. Letztere
            <acronym>SQL</acronym> Statements können zwar mit
           <classname>Zend_Db_Statement</classname> ausgeführt werden, aber Methoden die Zeilen
            oder Ergebnisse liefern können bei diesen nicht verwendet werden.
        </para>

        <sect3 id="zend.db.statement.fetching.fetch">
            <title>Holen einer einzelnen Zeile eines Ergebnissatzes</title>

            <para>
                Um eine einzelne Zeile eines Ergebnissatzes aubzurufen kann die
                <methodname>fetch()</methodname> Methode des Statement Objekts verwendet werden.
                Alle drei Argumente dieser Methode sind optional:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>Fetch Style</emphasis> ist das erste Argument. Es steuert die
                        Struktur in welcher die Zeile zurück gegeben wird. In
                        <link linkend="zend.db.adapter.select.fetch-mode">diesem Kapitel</link>
                        befindet sich eine Beschreibung der gültigen Werte und der entsprechenden
                        Datenformaten.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Cursor Ausrichtung</emphasis> ist das zweite Argument. Standard
                        ist <constant>Zend_Db::FETCH_ORI_NEXT</constant>, was einfach bedeutet das
                        für jeden Aufruf von <methodname>fetch()</methodname> die nächste Zeile des
                        Ergebnissatzes, in der Reihenfolge des <acronym>RDBMS</acronym>, zurück
                        gegeben wird.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Offset</emphasis> ist das dritte Argument. Wenn die Cursor
                        Ausrichtung <constant>Zend_Db::FETCH_ORI_ABS</constant> ist, dann ist die
                        Offset-Nummer die ordinale Nummer der Zeile die zurück gegeben wird. Wenn
                        die Cursor Ausrichtung <constant>Zend_Db::FETCH_ORI_REL</constant>, dann ist
                        die Offset-Nummer relativ zu der Cursorposition bevor
                        <methodname>fetch()</methodname> aufgerufen wurde.
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                <methodname>fetch()</methodname> gibt <constant>FALSE</constant> zurück wenn alle
                Zeilen des Ergbnissatzes geholt wurden.
            </para>

            <example id="zend.db.statement.fetching.fetch.example">
                <title>Nutzung fetch() in einer Schleife</title>

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

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

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

        <sect3 id="zend.db.statement.fetching.fetchall">
            <title>Holen eines gesamten Ergebnissatzes</title>

            <para>
                Um alle Zeilen eines Ergebnissatzes in einem Schritt abzurufen wird die
                <methodname>fetchAll()</methodname> Methode verwendet. Dies ist gleichbedeutend mit
                dem Aufruf der <methodname>fetch()</methodname> Methode in einer Schleife und dem
                Speichern der Rückgabewerte in einem Array. Die <methodname>fetchAll()</methodname>
                Methode akzeptiert zwei Argumente. Das Erste ist der Fetch Style, wie oben
                beschrieben, und das Zweite gibt die Nummer der zurück zu gebenden Spalte an, wenn
                der Fetch Style <constant>Zend_Db::FETCH_COLUMN</constant> ist.
            </para>

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

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

$rows = $stmt->fetchAll();

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

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

        <sect3 id="zend.db.statement.fetching.fetch-mode">
            <title>Ändern des Fetch Modus</title>

            <para>
                Standardmäßig gibt das Statement Objekt Zeilen des Ergebnissatzes als assoziatives
                Array, mapping column names to column values, zurück. Ein anderes Format für die
                Datenrückgabe der Statementklasse kann genau wie bei der Adapterklasse angegeben
                werden. Die <methodname>setFetchMode()</methodname> Methode des Statement Objekts
                wird verwendet um den Fetch-Modus anzugeben. Dazu werden die
                <classname>Zend_Db</classname> Klassen Konstanten <constant>FETCH_ASSOC</constant>,
                <constant>FETCH_NUM</constant>, <constant>FETCH_BOTH</constant>,
                <constant>FETCH_COLUMN</constant> und <constant>FETCH_OBJ</constant> verwendet.
                Weiter Informationen über diese Modi gibt es in <link
                    linkend="zend.db.adapter.select.fetch-mode">diesem Kapitel</link>. Nachfolgende
                Aufrufe der Statement Methoden <methodname>fetch()</methodname> und
                <methodname>fetchAll()</methodname> benutzen den neu gesetzten Fetch-Modus.
            </para>

            <example id="zend.db.statement.fetching.fetch-mode.example">
                <title>Ändern des Fetch-Modus</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>
                Weitere Informationen unter <ulink
                    url="http://www.php.net/PDOStatement-setFetchMode">PDOStatement::setFetchMode()</ulink>.
            </para>
        </sect3>

        <sect3 id="zend.db.statement.fetching.fetchcolumn">
            <title>Holen einer einzelnen Spalte eines Ergebnissatzes</title>

            <para>
                <methodname>fetchColumn()</methodname> wird verwendet mm eine einzelne Spalte eines
                Ergebnissatzes zurück zu geben. Das optionale Argument ist der Integer Index der
                Spalte die zurück gegeben werden soll. Der Standardwert ist 0. Diese Methode gibt
                einen scalaren Wert zurück, oder <constant>FALSE</constant> wenn alle Zeilen des
                Ergebnissatzes bereits geholt wurden.
            </para>

            <para>
                Zu beachten ist, dass diese Methode anders als die
                <methodname>fetchCol()</methodname> Methode der Adapterklasse arbeitet. Die
                <methodname>fetchColumn()</methodname> Methode der Statementklasse gibt einen
                einzelnen Wert einer Zeile zurück. Die <methodname>fetchCol()</methodname> Methode
                der Adapterklasse hingegen gibt ein Array von Werten der ersten Spalte aller Zeilen
                eines Ergebnissatzes zurück.
            </para>

            <example id="zend.db.statement.fetching.fetchcolumn.example">
                <title>Nutzung von 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>
                Weitere Informationen unter <ulink
                    url="http://www.php.net/PDOStatement-fetchColumn">PDOStatement::fetchColumn()</ulink>.
            </para>
        </sect3>

        <sect3 id="zend.db.statement.fetching.fetchobject">
            <title>Holen einer Zeile als Objekt</title>

            <para>
                Um eine Zeile eines Ergebnissatzes zu holen, die wie ein Objekt strukturiert ist,
                wird die <methodname>fetchObject()</methodname> Methode verwendet. Diese Methode
                nimmt zwei optionale Argumente entgegen. Das erste Argument ist ein String der den
                Klassenname des zurück zu gebenden Objekts enthält, standard ist 'stdClass'. Das
                zweite Argument ist ein Array von Werten, die an den Konstruktor des Objekts
                übergeben werden.
            </para>

            <example id="zend.db.statement.fetching.fetchobject.example">
                <title>Nutzung von 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>
                Weitere Informationen unter <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>