documentation/manual/de/module_specs/Zend_Db_Statement.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 21829 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="zend.db.statement">
   5     <title>Zend_Db_Statement</title>
   6
   7     <para>
   8         Zusätzlich zu den herkömmlichen Methoden wie <methodname>fetchAll()</methodname> und
   9         <methodname>insert()</methodname>, beschrieben in <link
  10             linkend="zend.db.adapter">Zend_Db_Adapter</link>, kann auch ein Statement-Objekt
  11         verwendet werden, um zusätzliche Möglichkeiten beim Ausführen von Abfragen und holen von
  12         Ergebnissätzen zu erhalten. Dieser Abschnitt beschreibt wie eine Instanz eines
  13         Statement-Objekts erzeugt wird, und wie dessen Methoden verwendet werden.
  14     </para>
  15
  16     <para>
  17         <classname>Zend_Db_Statement</classname> basiert auf dem PDOStatement
  18         Objekt aus der <ulink url="http://www.php.net/pdo">PHP Data Objects</ulink> Erweiterung.
  19     </para>
  20
  21     <sect2 id="zend.db.statement.creating">
  22         <title>Erzeugung von Statement Objekten</title>
  23
  24         <para>
  25             Normalerweise wird ein Statement Objekt von der <methodname>query()</methodname>
  26             Methode der Datenbank Adapterklasse zurück gegeben. Diese Methode ist der
  27             grundsätzliche Weg um ein beliebiges <acronym>SQL</acronym> Statement vor zu bereiten.
  28             Das erste Argument ist ein String, der das <acronym>SQL</acronym> Statement enthält. Das
  29             optionale zweite Argument ist ein Array von Werten, verknüpft mit Parameterplatzhaltern
  30             im <acronym>SQL</acronym> String.
  31         </para>
  32
  33         <example id="zend.db.statement.creating.example1">
  34             <title>Erzeugung eines SQL Statement Objekts mit query()</title>
  35
  36             <programlisting language="php"><![CDATA[
  37 $stmt = $db->query(
  38             'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?',
  39             array('goofy', 'FIXED')
  40         );
  41 ]]></programlisting>
  42         </example>
  43
  44         <para>
  45             Das Statement Objekt entspricht einem <acronym>SQL</acronym> Statement welches
  46             vorbereitet und einmalig mit angegebenen verknüpften Werten ausgeführt wurde. War das
  47             Statement eine <acronym>SELECT</acronym> Abfrage, oder irgendein Statement welches ein
  48             Ergebnissatz zurück gibt, so ist es nun bereit um Ergebnisse zu holen.
  49         </para>
  50
  51         <para>
  52             Ein Statement kann ebenfalls mit dem Konstruktor erzeugt werden, auch wenn dies eine
  53             weniger typische Nutzung ist. Es existiert jedoch keine factory Methode um das Objekt zu
  54             erzeugen, weßhalb die entsprechende Statementklasse geladen, und ihr Konstruktor
  55             aufgerufen werden muss. Als erstes Argument muss das Adapterobjekt übergeben werden und
  56             als zweites Argument ein String welcher das <acronym>SQL</acronym> Statement enthält.
  57             Das Statement ist dadurch vorbereitet, jedoch nicht Ausgeführt.
  58         </para>
  59
  60         <example id="zend.db.statement.creating.example2">
  61             <title>Nutzung des SQL Statement Konstruktors</title>
  62
  63             <programlisting language="php"><![CDATA[
  64 $sql = 'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?';
  65
  66 $stmt = new Zend_Db_Statement_Mysqli($db, $sql);
  67 ]]></programlisting>
  68         </example>
  69     </sect2>
  70
  71     <sect2 id="zend.db.statement.executing">
  72         <title>Ausführen eines Statements</title>
  73
  74         <para>
  75             Ein Statement Objekt muss ausgeführt werden wenn es über den Konstruktor erzeugt wurde,
  76             oder kann, wenn es mehrere Male hintereinander ausgeführt werden soll. Dazu wird die
  77             <methodname>execute()</methodname> Methode des Statement Objekts verwendet. Das einzige
  78             Argument ist ein Array von Werten, welche mit Parameterplatzhaltern im Statement
  79             verknüpft werden.
  80         </para>
  81
  82         <para>
  83             Wenn <emphasis>positionierte Parameter</emphasis>, oder solche, die mit dem Fragezeichen
  84             ('<emphasis>?</emphasis>') verwendet werden, muss ein einfaches Array übergeben werden.
  85         </para>
  86
  87         <example id="zend.db.statement.executing.example1">
  88             <title>Ausführen eines Statements mit positionierten Parametern</title>
  89
  90             <programlisting language="php"><![CDATA[
  91 $sql = 'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?';
  92
  93 $stmt = new Zend_Db_Statement_Mysqli($db, $sql);
  94
  95 $stmt->execute(array('goofy', 'FIXED'));
  96 ]]></programlisting>
  97         </example>
  98
  99         <para>
 100             Wenn <emphasis>benannte Parameter</emphasis>, oder solche die mit einem String und
 101             voranstehenden Doppelpunkt ('<emphasis>:</emphasis>') bezeichnet werden, verwendet
 102             werden, muss ein assoziatives Array übergeben werden. Die Schlüssel dieses Arrays müssen
 103             den Parameternamen entsprechen.
 104         </para>
 105
 106         <example id="zend.db.statement.executing.example2">
 107             <title>Ausführen eines Statements mit benannten Parametern</title>
 108
 109             <programlisting language="php"><![CDATA[
 110 $sql = 'SELECT * FROM bugs WHERE ' .
 111        'reported_by = :reporter AND bug_status = :status';
 112
 113 $stmt = new Zend_Db_Statement_Mysqli($db, $sql);
 114
 115 $stmt->execute(array(':reporter' => 'goofy', ':status' => 'FIXED'));
 116 ]]></programlisting>
 117         </example>
 118
 119         <para>
 120             <acronym>PDO</acronym> Statements unterstützen sowohl postionierte als auch benannte
 121             Parameter, jedoch nicht beide Typen in einem einzelnen <acronym>SQL</acronym> Statement.
 122             Einige der <classname>Zend_Db_Statement</classname> Klassen für nicht-PDO Erweiterungen
 123             könnten nur einen Typ von Parametern unterstützen.
 124         </para>
 125     </sect2>
 126
 127     <sect2 id="zend.db.statement.fetching">
 128         <title>Holen von Ergebnissen eines SELECT Statements</title>
 129
 130         <para>
 131             Es können Methoden des Statement Objekts aufgefufen werden um Zeilen von
 132             <acronym>SQL</acronym> Statements zu erhalten die Ergebnissätze erzeugen.
 133             <acronym>SELECT</acronym>, <acronym>SHOW</acronym>, <acronym>DESCRIBE</acronym> und
 134             <acronym>EXPLAIN</acronym> sind Beispiele von von Statements die Ergebnissätze erzeugen.
 135             <acronym>INSERT</acronym>, <acronym>UPDATE</acronym> und <acronym>DELETE</acronym> sind
 136             Beispiele von Statements die keine Ergebnissätze erzeugen. Letztere
 137             <acronym>SQL</acronym> Statements können zwar mit
 138            <classname>Zend_Db_Statement</classname> ausgeführt werden, aber Methoden die Zeilen
 139             oder Ergebnisse liefern können bei diesen nicht verwendet werden.
 140         </para>
 141
 142         <sect3 id="zend.db.statement.fetching.fetch">
 143             <title>Holen einer einzelnen Zeile eines Ergebnissatzes</title>
 144
 145             <para>
 146                 Um eine einzelne Zeile eines Ergebnissatzes aubzurufen kann die
 147                 <methodname>fetch()</methodname> Methode des Statement Objekts verwendet werden.
 148                 Alle drei Argumente dieser Methode sind optional:
 149             </para>
 150
 151             <itemizedlist>
 152                 <listitem>
 153                     <para>
 154                         <emphasis>Fetch Style</emphasis> ist das erste Argument. Es steuert die
 155                         Struktur in welcher die Zeile zurück gegeben wird. In
 156                         <link linkend="zend.db.adapter.select.fetch-mode">diesem Kapitel</link>
 157                         befindet sich eine Beschreibung der gültigen Werte und der entsprechenden
 158                         Datenformaten.
 159                     </para>
 160                 </listitem>
 161
 162                 <listitem>
 163                     <para>
 164                         <emphasis>Cursor Ausrichtung</emphasis> ist das zweite Argument. Standard
 165                         ist <constant>Zend_Db::FETCH_ORI_NEXT</constant>, was einfach bedeutet das
 166                         für jeden Aufruf von <methodname>fetch()</methodname> die nächste Zeile des
 167                         Ergebnissatzes, in der Reihenfolge des <acronym>RDBMS</acronym>, zurück
 168                         gegeben wird.
 169                     </para>
 170                 </listitem>
 171
 172                 <listitem>
 173                     <para>
 174                         <emphasis>Offset</emphasis> ist das dritte Argument. Wenn die Cursor
 175                         Ausrichtung <constant>Zend_Db::FETCH_ORI_ABS</constant> ist, dann ist die
 176                         Offset-Nummer die ordinale Nummer der Zeile die zurück gegeben wird. Wenn
 177                         die Cursor Ausrichtung <constant>Zend_Db::FETCH_ORI_REL</constant>, dann ist
 178                         die Offset-Nummer relativ zu der Cursorposition bevor
 179                         <methodname>fetch()</methodname> aufgerufen wurde.
 180                     </para>
 181                 </listitem>
 182             </itemizedlist>
 183
 184             <para>
 185                 <methodname>fetch()</methodname> gibt <constant>FALSE</constant> zurück wenn alle
 186                 Zeilen des Ergbnissatzes geholt wurden.
 187             </para>
 188
 189             <example id="zend.db.statement.fetching.fetch.example">
 190                 <title>Nutzung fetch() in einer Schleife</title>
 191
 192                 <programlisting language="php"><![CDATA[
 193 $stmt = $db->query('SELECT * FROM bugs');
 194
 195 while ($row = $stmt->fetch()) {
 196     echo $row['bug_description'];
 197 }
 198 ]]></programlisting>
 199             </example>
 200
 201             <para>
 202                 Weitere Informationen unter
 203                 <ulink url="http://www.php.net/PDOStatement-fetch">PDOStatement::fetch()</ulink>.
 204             </para>
 205         </sect3>
 206
 207         <sect3 id="zend.db.statement.fetching.fetchall">
 208             <title>Holen eines gesamten Ergebnissatzes</title>
 209
 210             <para>
 211                 Um alle Zeilen eines Ergebnissatzes in einem Schritt abzurufen wird die
 212                 <methodname>fetchAll()</methodname> Methode verwendet. Dies ist gleichbedeutend mit
 213                 dem Aufruf der <methodname>fetch()</methodname> Methode in einer Schleife und dem
 214                 Speichern der Rückgabewerte in einem Array. Die <methodname>fetchAll()</methodname>
 215                 Methode akzeptiert zwei Argumente. Das Erste ist der Fetch Style, wie oben
 216                 beschrieben, und das Zweite gibt die Nummer der zurück zu gebenden Spalte an, wenn
 217                 der Fetch Style <constant>Zend_Db::FETCH_COLUMN</constant> ist.
 218             </para>
 219
 220             <example id="zend.db.statement.fetching.fetchall.example">
 221                 <title>Nutzung von fetchAll()</title>
 222
 223                 <programlisting language="php"><![CDATA[
 224 $stmt = $db->query('SELECT * FROM bugs');
 225
 226 $rows = $stmt->fetchAll();
 227
 228 echo $rows[0]['bug_description'];
 229 ]]></programlisting>
 230             </example>
 231
 232             <para>
 233                 Weitere Informationen unter <ulink
 234                     url="http://www.php.net/PDOStatement-fetchAll">PDOStatement::fetchAll()</ulink>.
 235             </para>
 236         </sect3>
 237
 238         <sect3 id="zend.db.statement.fetching.fetch-mode">
 239             <title>Ändern des Fetch Modus</title>
 240
 241             <para>
 242                 Standardmäßig gibt das Statement Objekt Zeilen des Ergebnissatzes als assoziatives
 243                 Array, mapping column names to column values, zurück. Ein anderes Format für die
 244                 Datenrückgabe der Statementklasse kann genau wie bei der Adapterklasse angegeben
 245                 werden. Die <methodname>setFetchMode()</methodname> Methode des Statement Objekts
 246                 wird verwendet um den Fetch-Modus anzugeben. Dazu werden die
 247                 <classname>Zend_Db</classname> Klassen Konstanten <constant>FETCH_ASSOC</constant>,
 248                 <constant>FETCH_NUM</constant>, <constant>FETCH_BOTH</constant>,
 249                 <constant>FETCH_COLUMN</constant> und <constant>FETCH_OBJ</constant> verwendet.
 250                 Weiter Informationen über diese Modi gibt es in <link
 251                     linkend="zend.db.adapter.select.fetch-mode">diesem Kapitel</link>. Nachfolgende
 252                 Aufrufe der Statement Methoden <methodname>fetch()</methodname> und
 253                 <methodname>fetchAll()</methodname> benutzen den neu gesetzten Fetch-Modus.
 254             </para>
 255
 256             <example id="zend.db.statement.fetching.fetch-mode.example">
 257                 <title>Ändern des Fetch-Modus</title>
 258
 259                 <programlisting language="php"><![CDATA[
 260 $stmt = $db->query('SELECT * FROM bugs');
 261
 262 $stmt->setFetchMode(Zend_Db::FETCH_NUM);
 263
 264 $rows = $stmt->fetchAll();
 265
 266 echo $rows[0][0];
 267 ]]></programlisting>
 268             </example>
 269
 270             <para>
 271                 Weitere Informationen unter <ulink
 272                     url="http://www.php.net/PDOStatement-setFetchMode">PDOStatement::setFetchMode()</ulink>.
 273             </para>
 274         </sect3>
 275
 276         <sect3 id="zend.db.statement.fetching.fetchcolumn">
 277             <title>Holen einer einzelnen Spalte eines Ergebnissatzes</title>
 278
 279             <para>
 280                 <methodname>fetchColumn()</methodname> wird verwendet mm eine einzelne Spalte eines
 281                 Ergebnissatzes zurück zu geben. Das optionale Argument ist der Integer Index der
 282                 Spalte die zurück gegeben werden soll. Der Standardwert ist 0. Diese Methode gibt
 283                 einen scalaren Wert zurück, oder <constant>FALSE</constant> wenn alle Zeilen des
 284                 Ergebnissatzes bereits geholt wurden.
 285             </para>
 286
 287             <para>
 288                 Zu beachten ist, dass diese Methode anders als die
 289                 <methodname>fetchCol()</methodname> Methode der Adapterklasse arbeitet. Die
 290                 <methodname>fetchColumn()</methodname> Methode der Statementklasse gibt einen
 291                 einzelnen Wert einer Zeile zurück. Die <methodname>fetchCol()</methodname> Methode
 292                 der Adapterklasse hingegen gibt ein Array von Werten der ersten Spalte aller Zeilen
 293                 eines Ergebnissatzes zurück.
 294             </para>
 295
 296             <example id="zend.db.statement.fetching.fetchcolumn.example">
 297                 <title>Nutzung von fetchColumn()</title>
 298
 299                 <programlisting language="php"><![CDATA[
 300 $stmt = $db->query('SELECT bug_id, bug_description, bug_status FROM bugs');
 301
 302 $bug_status = $stmt->fetchColumn(2);
 303 ]]></programlisting>
 304             </example>
 305
 306             <para>
 307                 Weitere Informationen unter <ulink
 308                     url="http://www.php.net/PDOStatement-fetchColumn">PDOStatement::fetchColumn()</ulink>.
 309             </para>
 310         </sect3>
 311
 312         <sect3 id="zend.db.statement.fetching.fetchobject">
 313             <title>Holen einer Zeile als Objekt</title>
 314
 315             <para>
 316                 Um eine Zeile eines Ergebnissatzes zu holen, die wie ein Objekt strukturiert ist,
 317                 wird die <methodname>fetchObject()</methodname> Methode verwendet. Diese Methode
 318                 nimmt zwei optionale Argumente entgegen. Das erste Argument ist ein String der den
 319                 Klassenname des zurück zu gebenden Objekts enthält, standard ist 'stdClass'. Das
 320                 zweite Argument ist ein Array von Werten, die an den Konstruktor des Objekts
 321                 übergeben werden.
 322             </para>
 323
 324             <example id="zend.db.statement.fetching.fetchobject.example">
 325                 <title>Nutzung von fetchObject()</title>
 326
 327                 <programlisting language="php"><![CDATA[
 328 $stmt = $db->query('SELECT bug_id, bug_description, bug_status FROM bugs');
 329
 330 $obj = $stmt->fetchObject();
 331
 332 echo $obj->bug_description;
 333 ]]></programlisting>
 334             </example>
 335
 336             <para>
 337                 Weitere Informationen unter <ulink
 338                     url="http://www.php.net/PDOStatement-fetchObject">PDOStatement::fetchObject()</ulink>.
 339             </para>
 340         </sect3>
 341     </sect2>
 342
 343     <!--
 344       @todo: binding parameters is not working yet.
 345
 346     <sect2 id="zend.db.statement.binding-param">
 347         <title>Binding PHP Variables to Parameters</title>
 348
 349         <para>
 350         </para>
 351
 352         <example id="zend.db.statement.binding-param.example">
 353             <title>Binding parameters from PHP variables</title>
 354
 355             <programlisting language="php"><![CDATA[
 356 ]]></programlisting>
 357         </example>
 358
 359         <para>
 360             See also <ulink
 361                 url="http://www.php.net/PDOStatement-bindParam">PDOStatement::bindParam()</ulink>.
 362         </para>
 363     </sect2>
 364     -->
 365
 366     <!--
 367       @todo: binding columns is not working yet.
 368     <sect2 id="zend.db.statement.binding-column">
 369         <title>Binding PHP Variables to Query Results</title>
 370
 371         <para>
 372         </para>
 373
 374         <example id="zend.db.statement.binding-column.example">
 375             <title>Binding results to PHP variables</title>
 376
 377             <programlisting language="php"><![CDATA[
 378 ]]></programlisting>
 379         </example>
 380
 381         <para>
 382             See also <ulink
 383                 url="http://www.php.net/PDOStatement-bindColumn">PDOStatement::bindColumn()</ulink>.
 384         </para>
 385     </sect2>
 386     -->
 387 </sect1>