repo_zf1/documentation/manual/de/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>
        Zusätzlich zu den herkömmlichen Methoden wie <methodname>fetchAll()</methodname> und
        <methodname>insert()</methodname>, beschrieben in <xref linkend="zend.db.adapter" />, 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 SELECT 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.
            SELECT, SHOW, DESCRIBE und EXPLAIN sind Beispiele von von Statements die Ergebnissätze
            erzeugen. INSERT, UPDATE und DELETE 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. Unter
                        <xref linkend="zend.db.adapter.select.fetch-mode" /> 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 Zend_Db::FETCH_ORI_NEXT, 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 Zend_Db::FETCH_ORI_ABS ist, dann ist die
                        Offset-Nummer die ordinale Nummer der Zeile die zurück gegeben wird.
                        Wenn die Cursor Ausrichtung Zend_Db::FETCH_ORI_REL, 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 Zend_Db::FETCH_COLUMN 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 FETCH_ASSOC, FETCH_NUM,
                FETCH_BOTH, FETCH_COLUMN und FETCH_OBJ verwendet. Weiter Informationenüber diese
                Modi gibt es unter <xref linkend="zend.db.adapter.select.fetch-mode" />.
                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>