documentation/manual/en/module_specs/Zend_Db_Statement.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.db.statement">
   4     <title>Zend_Db_Statement</title>
   5
   6     <para>
   7         In addition to convenient methods such as <methodname>fetchAll()</methodname> and
   8         <methodname>insert()</methodname> documented in <link
   9             linkend="zend.db.adapter">Zend_Db_Adapter</link>, you can use a statement object to gain
  10         more options for running queries and fetching result sets. This section describes how to get
  11         an instance of a statement object, and how to use its methods.
  12     </para>
  13
  14     <para>
  15         <classname>Zend_Db_Statement</classname> is based on the PDOStatement object in the
  16         <ulink url="http://www.php.net/pdo">PHP Data Objects</ulink> extension.
  17     </para>
  18
  19     <sect2 id="zend.db.statement.creating">
  20         <title>Creating a Statement</title>
  21
  22         <para>
  23             Typically, a statement object is returned by the
  24             <methodname>query()</methodname> method of the database Adapter class.
  25             This method is a general way to prepare any <acronym>SQL</acronym> statement.
  26             The first argument is a string containing an <acronym>SQL</acronym> statement.
  27             The optional second argument is an array of values to bind
  28             to parameter placeholders in the <acronym>SQL</acronym> string.
  29         </para>
  30
  31         <example id="zend.db.statement.creating.example1">
  32             <title>Creating a SQL statement object with query()</title>
  33
  34             <programlisting language="php"><![CDATA[
  35 $stmt = $db->query(
  36             'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?',
  37             array('goofy', 'FIXED')
  38         );
  39 ]]></programlisting>
  40         </example>
  41
  42         <para>
  43             The statement object corresponds to a <acronym>SQL</acronym> statement that has been
  44             prepared, and executed once with the bind-values specified.
  45             If the statement was a <acronym>SELECT</acronym> query or other type of statement
  46             that returns a result set, it is now ready to fetch results.
  47         </para>
  48
  49         <para>
  50             You can create a statement with its constructor, but this is less
  51             typical usage. There is no factory method to create this object,
  52             so you need to load the specific statement class and call its
  53             constructor. Pass the Adapter object as the first argument, and
  54             a string containing an <acronym>SQL</acronym> statement as the second argument.
  55             The statement is prepared, but not executed.
  56         </para>
  57
  58         <example id="zend.db.statement.creating.example2">
  59             <title>Using a SQL statement constructor</title>
  60
  61             <programlisting language="php"><![CDATA[
  62 $sql = 'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?';
  63
  64 $stmt = new Zend_Db_Statement_Mysqli($db, $sql);
  65 ]]></programlisting>
  66         </example>
  67     </sect2>
  68
  69     <sect2 id="zend.db.statement.executing">
  70         <title>Executing a Statement</title>
  71
  72         <para>
  73             You need to execute a statement object if you create it using its
  74             constructor, or if you want to execute the same statement multiple
  75             times. Use the <methodname>execute()</methodname> method of the statement
  76             object. The single argument is an array of value to bind to
  77             parameter placeholders in the statement.
  78         </para>
  79
  80         <para>
  81             If you use <emphasis>positional parameters</emphasis>, or those
  82             that are marked with a question mark symbol ('<emphasis>?</emphasis>'), pass
  83             the bind values in a plain array.
  84         </para>
  85
  86         <example id="zend.db.statement.executing.example1">
  87             <title>Executing a statement with positional parameters</title>
  88
  89             <programlisting language="php"><![CDATA[
  90 $sql = 'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?';
  91
  92 $stmt = new Zend_Db_Statement_Mysqli($db, $sql);
  93
  94 $stmt->execute(array('goofy', 'FIXED'));
  95 ]]></programlisting>
  96         </example>
  97
  98         <para>
  99             If you use <emphasis>named parameters</emphasis>, or those that are
 100             indicated by a string identifier preceded by a colon character
 101             ('<emphasis>:</emphasis>'), pass the bind values in an associative array.
 102             The keys of this array should match the parameter names.
 103         </para>
 104
 105         <example id="zend.db.statement.executing.example2">
 106             <title>Executing a statement with named parameters</title>
 107
 108             <programlisting language="php"><![CDATA[
 109 $sql = 'SELECT * FROM bugs WHERE ' .
 110        'reported_by = :reporter AND bug_status = :status';
 111
 112 $stmt = new Zend_Db_Statement_Mysqli($db, $sql);
 113
 114 $stmt->execute(array(':reporter' => 'goofy', ':status' => 'FIXED'));
 115 ]]></programlisting>
 116         </example>
 117
 118         <para>
 119             <acronym>PDO</acronym> statements support both positional parameters and named
 120             parameters, but not both types in a single <acronym>SQL</acronym> statement. Some of
 121             the <classname>Zend_Db_Statement</classname> classes for non-PDO extensions may support
 122             only one type of parameter or the other.
 123         </para>
 124     </sect2>
 125
 126     <sect2 id="zend.db.statement.fetching">
 127         <title>Fetching Results from a SELECT Statement</title>
 128
 129         <para>
 130             You can call methods on the statement object to retrieve rows from
 131             <acronym>SQL</acronym> statements that produce result set. <acronym>SELECT</acronym>,
 132             <acronym>SHOW</acronym>, <acronym>DESCRIBE</acronym> and <acronym>EXPLAIN</acronym> are
 133             examples of statements that produce a result set. <acronym>INSERT</acronym>,
 134             <acronym>UPDATE</acronym>, and <acronym>DELETE</acronym> are examples of statements that
 135             don't produce a result set. You can execute the latter <acronym>SQL</acronym> statements
 136             using <classname>Zend_Db_Statement</classname>, but you cannot call methods to fetch
 137             rows of results from them.
 138         </para>
 139
 140         <sect3 id="zend.db.statement.fetching.fetch">
 141             <title>Fetching a Single Row from a Result Set</title>
 142
 143             <para>
 144                 To retrieve one row from the result set, use the
 145                 <methodname>fetch()</methodname> method of the statement object.
 146                 All three arguments of this method are optional:
 147             </para>
 148
 149             <itemizedlist>
 150                 <listitem>
 151                     <para>
 152                         <emphasis>Fetch style</emphasis> is the
 153                         first argument. This controls the structure in which
 154                         the row is returned.
 155                         See <link linkend="zend.db.adapter.select.fetch-mode">this chapter</link>
 156                         for a description of the valid values and the
 157                         corresponding data formats.
 158                     </para>
 159                 </listitem>
 160
 161                 <listitem>
 162                     <para>
 163                         <emphasis>Cursor orientation</emphasis>
 164                         is the second argument. The default is
 165                         <constant>Zend_Db::FETCH_ORI_NEXT</constant>, which simply means that each
 166                         call to <methodname>fetch()</methodname> returns the next row in
 167                         the result set, in the order returned by the <acronym>RDBMS</acronym>.
 168                     </para>
 169                 </listitem>
 170
 171                 <listitem>
 172                     <para>
 173                         <emphasis>Offset</emphasis> is the third
 174                         argument.
 175                         If the cursor orientation is <constant>Zend_Db::FETCH_ORI_ABS</constant>,
 176                         then the offset number is the ordinal number of the row to return.
 177                         If the cursor orientation is <constant>Zend_Db::FETCH_ORI_REL</constant>,
 178                         then the offset number is relative to the cursor
 179                         position before <methodname>fetch()</methodname> was called.
 180                     </para>
 181                 </listitem>
 182             </itemizedlist>
 183
 184             <para>
 185                 <methodname>fetch()</methodname> returns <constant>FALSE</constant> if all rows of
 186                 the result set have been fetched.
 187             </para>
 188
 189             <example id="zend.db.statement.fetching.fetch.example">
 190                 <title>Using fetch() in a loop</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                 See also <ulink
 203                    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>Fetching a Complete Result Set</title>
 209
 210             <para>
 211                 To retrieve all the rows of the result set in one step, use the
 212                 <methodname>fetchAll()</methodname> method. This is equivalent to calling
 213                 the <methodname>fetch()</methodname> method in a loop and returning all
 214                 the rows in an array. The <methodname>fetchAll()</methodname> method accepts
 215                 two arguments. The first is the fetch style, as described above,
 216                 and the second indicates the number of the column to return,
 217                 when the fetch style is <constant>Zend_Db::FETCH_COLUMN</constant>.
 218             </para>
 219
 220             <example id="zend.db.statement.fetching.fetchall.example">
 221                 <title>Using 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                 See also <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>Changing the Fetch Mode</title>
 240
 241             <para>
 242                 By default, the statement object returns rows of the result set
 243                 as associative arrays, mapping column names to column values.
 244                 You can specify a different format for the statement class to
 245                 return rows, just as you can in the Adapter class. You can use
 246                 the <methodname>setFetchMode()</methodname> method of the statement object
 247                 to specify the fetch mode. Specify the fetch mode using
 248                 <classname>Zend_Db</classname> class constants <constant>FETCH_ASSOC</constant>,
 249                 <constant>FETCH_NUM</constant>, <constant>FETCH_BOTH</constant>,
 250                 <constant>FETCH_COLUMN</constant>, and <constant>FETCH_OBJ</constant>.
 251                 See <link linkend="zend.db.adapter.select.fetch-mode">this chapter</link>
 252                 for more information on these modes. Subsequent calls to the statement methods
 253                 <methodname>fetch()</methodname> or <methodname>fetchAll()</methodname> use the
 254                 fetch mode that you specify.
 255             </para>
 256
 257             <example id="zend.db.statement.fetching.fetch-mode.example">
 258                 <title>Setting the fetch mode</title>
 259
 260                 <programlisting language="php"><![CDATA[
 261 $stmt = $db->query('SELECT * FROM bugs');
 262
 263 $stmt->setFetchMode(Zend_Db::FETCH_NUM);
 264
 265 $rows = $stmt->fetchAll();
 266
 267 echo $rows[0][0];
 268 ]]></programlisting>
 269             </example>
 270
 271             <para>
 272                 See also <ulink
 273                     url="http://www.php.net/PDOStatement-setFetchMode">PDOStatement::setFetchMode()</ulink>.
 274             </para>
 275         </sect3>
 276
 277         <sect3 id="zend.db.statement.fetching.fetchcolumn">
 278             <title>Fetching a Single Column from a Result Set</title>
 279
 280             <para>
 281                 To return a single column from the next row of the result set,
 282                 use <methodname>fetchColumn()</methodname>. The optional argument is the
 283                 integer index of the column, and it defaults to 0. This method
 284                 returns a scalar value, or <constant>FALSE</constant> if all rows of
 285                 the result set have been fetched.
 286             </para>
 287
 288             <para>
 289                 Note this method operates differently than the
 290                 <methodname>fetchCol()</methodname> method of the Adapter class.
 291                 The <methodname>fetchColumn()</methodname> method of a statement returns a
 292                 single value from one row.
 293                 The <methodname>fetchCol()</methodname> method of an adapter returns an
 294                 array of values, taken from the first column of all rows of the
 295                 result set.
 296             </para>
 297
 298             <example id="zend.db.statement.fetching.fetchcolumn.example">
 299                 <title>Using fetchColumn()</title>
 300
 301                 <programlisting language="php"><![CDATA[
 302 $stmt = $db->query('SELECT bug_id, bug_description, bug_status FROM bugs');
 303
 304 $bug_status = $stmt->fetchColumn(2);
 305 ]]></programlisting>
 306             </example>
 307
 308             <para>
 309                 See also <ulink
 310                     url="http://www.php.net/PDOStatement-fetchColumn">PDOStatement::fetchColumn()</ulink>.
 311             </para>
 312         </sect3>
 313
 314         <sect3 id="zend.db.statement.fetching.fetchobject">
 315             <title>Fetching a Row as an Object</title>
 316
 317             <para>
 318                 To retrieve a row from the result set structured as an object,
 319                 use the <methodname>fetchObject()</methodname>. This method takes two
 320                 optional arguments. The first argument is a string that names
 321                 the class name of the object to return; the default is
 322                 'stdClass'. The second argument is an array of values that
 323                 will be passed to the constructor of that class.
 324             </para>
 325
 326             <example id="zend.db.statement.fetching.fetchobject.example">
 327                 <title>Using fetchObject()</title>
 328
 329                 <programlisting language="php"><![CDATA[
 330 $stmt = $db->query('SELECT bug_id, bug_description, bug_status FROM bugs');
 331
 332 $obj = $stmt->fetchObject();
 333
 334 echo $obj->bug_description;
 335 ]]></programlisting>
 336             </example>
 337
 338             <para>
 339                 See also <ulink
 340                     url="http://www.php.net/PDOStatement-fetchObject">PDOStatement::fetchObject()</ulink>.
 341             </para>
 342         </sect3>
 343     </sect2>
 344
 345     <!--
 346       @todo: binding parameters is not working yet.
 347
 348     <sect2 id="zend.db.statement.binding-param">
 349
 350         <title>Binding PHP Variables to Parameters</title>
 351
 352         <para>
 353         </para>
 354
 355         <example id="zend.db.statement.binding-param.example">
 356             <title>Binding parameters from PHP variables</title>
 357
 358             <programlisting language="php"><![CDATA[
 359 ]]></programlisting>
 360         </example>
 361
 362         <para>
 363             See also <ulink
 364                 url="http://www.php.net/PDOStatement-bindParam">PDOStatement::bindParam()</ulink>.
 365         </para>
 366
 367     </sect2>
 368     -->
 369
 370     <!--
 371       @todo: binding columns is not working yet.
 372     <sect2 id="zend.db.statement.binding-column">
 373
 374         <title>Binding PHP Variables to Query Results</title>
 375
 376         <para>
 377         </para>
 378
 379         <example id="zend.db.statement.binding-column.example">
 380             <title>Binding results to PHP variables</title>
 381
 382             <programlisting language="php"><![CDATA[
 383 ]]></programlisting>
 384         </example>
 385
 386         <para>
 387             See also <ulink
 388                 url="http://www.php.net/PDOStatement-bindColumn">PDOStatement::bindColumn()</ulink>.
 389         </para>
 390
 391     </sect2>
 392     -->
 393 </sect1>