Source of: /manual/en/pdostatement.fetch.php
<?php
include_once $_SERVER['DOCUMENT_ROOT'] . '/include/shared-manual.inc';
$TOC = array();
$PARENTS = array();
include_once dirname(__FILE__) ."/toc/class.pdostatement.inc";
$setup = array (
'home' =>
array (
0 => 'index.php',
1 => 'PHP Manual',
),
'head' =>
array (
0 => 'UTF-8',
1 => 'en',
),
'this' =>
array (
0 => 'pdostatement.fetch.php',
1 => 'PDOStatement->fetch',
),
'up' =>
array (
0 => 'class.pdostatement.php',
1 => 'The PDOStatement class',
),
'prev' =>
array (
0 => 'pdostatement.execute.php',
1 => 'PDOStatement->execute',
),
'next' =>
array (
0 => 'pdostatement.fetchall.php',
1 => 'PDOStatement->fetchAll',
),
);
$setup["toc"] = $TOC;
$setup["parents"] = $PARENTS;
manual_setup($setup);
manual_header();
?>
<div id="pdostatement.fetch" class="refentry">
<div class="refnamediv">
<h1 class="refname">PDOStatement->fetch</h1>
<p class="verinfo">(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)</p><p class="refpurpose"><span class="refname">PDOStatement->fetch</span> — <span class="dc-title">
Fetches the next row from a result set
</span></p>
</div>
<a name="pdostatement.fetch.description"></a><div class="refsect1 description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type"><a href="language.pseudo-types.php#language.types.mixed" class="type mixed">mixed</a></span> <span class="methodname"><b>PDOStatement::fetch</b></span>
([ <span class="methodparam"><span class="type">int</span> <tt class="parameter">$fetch_style</tt><span class="initializer"> = PDO::FETCH_BOTH</span></span>
[, <span class="methodparam"><span class="type">int</span> <tt class="parameter">$cursor_orientation</tt><span class="initializer"> = PDO::FETCH_ORI_NEXT</span></span>
[, <span class="methodparam"><span class="type">int</span> <tt class="parameter">$cursor_offset</tt><span class="initializer"> = 0</span></span>
]]] )</div>
<p class="para rdfs-comment">
Fetches a row from a result set associated with a PDOStatement object. The
<i><tt class="parameter">fetch_style</tt></i>
parameter determines how PDO returns
the row.
</p>
</div>
<a name="pdostatement.fetch.parameters"></a><div class="refsect1 parameters">
<h3 class="title">Parameters</h3>
<p class="para">
</p><dl>
<dt class="varlistentry">
<span class="term"><i><tt class="parameter">fetch_style</tt></i>
</span>
</dt><dd class="listitem">
<p class="para">
Controls how the next row will be returned to the caller. This value
must be one of the <i>PDO::FETCH_*</i> constants,
defaulting to <i>PDO::FETCH_BOTH</i>.
</p><ul class="itemizedlist">
<li class="listitem"><p class="para">
<i>PDO::FETCH_ASSOC</i>: returns an array indexed by column
name as returned in your result set
</p></li>
<li class="listitem"><p class="para">
<i>PDO::FETCH_BOTH</i> (default): returns an array indexed by
both column name and 0-indexed column number as returned in your
result set
</p></li>
<li class="listitem"><p class="para">
<i>PDO::FETCH_BOUND</i>: returns <b><tt class="constant">TRUE</tt></b> and assigns the
values of the columns in your result set to the PHP variables to which
they were bound with the <a href="pdostatement.bindcolumn.php" class="function">PDOStatement::bindColumn()</a>
method
</p></li>
<li class="listitem"><p class="para">
<i>PDO::FETCH_CLASS</i>: returns a new instance of the
requested class, mapping the columns of the result set to named
properties in the class. If <i><tt class="parameter">fetch_style</tt></i>
includes PDO::FETCH_CLASSTYPE (e.g. <i>PDO::FETCH_CLASS |
PDO::FETCH_CLASSTYPE</i>) then the name of the class is
determined from a value of the first column.
</p></li>
<li class="listitem"><p class="para">
<i>PDO::FETCH_INTO</i>: updates an existing instance
of the requested class, mapping the columns of the result set to
named properties in the class
</p></li>
<li class="listitem"><p class="para">
<i>PDO::FETCH_LAZY</i>: combines
<i>PDO::FETCH_BOTH</i> and <i>PDO::FETCH_OBJ</i>,
creating the object variable names as they are accessed
</p></li>
<li class="listitem"><p class="para">
<i>PDO::FETCH_NUM</i>: returns an array indexed by column
number as returned in your result set, starting at column 0
</p></li>
<li class="listitem"><p class="para">
<i>PDO::FETCH_OBJ</i>: returns an anonymous object with
property names that correspond to the column names returned in your
result set
</p></li>
</ul><p>
</p>
</dd>
<dt class="varlistentry">
<span class="term"><i><tt class="parameter">cursor_orientation</tt></i>
</span>
</dt><dd class="listitem">
<p class="para">
For a PDOStatement object representing a scrollable cursor, this
value determines which row will be returned to the caller. This value
must be one of the <i>PDO::FETCH_ORI_*</i> constants,
defaulting to <i>PDO::FETCH_ORI_NEXT</i>. To request a
scrollable cursor for your PDOStatement object, you must set the
<i>PDO::ATTR_CURSOR</i> attribute to
<i>PDO::CURSOR_SCROLL</i> when you prepare the SQL
statement with <a href="pdo.prepare.php" class="function">PDO::prepare()</a>.
</p>
</dd>
<dt class="varlistentry">
<span class="term"><i><tt class="parameter">offset</tt></i>
</span>
</dt><dd class="listitem">
<p class="para">
For a PDOStatement object representing a scrollable cursor for which
the <i>cursor_orientation</i> parameter is set to
<i>PDO::FETCH_ORI_ABS</i>, this value specifies the
absolute number of the row in the result set that shall be fetched.
</p>
<p class="para">
For a PDOStatement object representing a scrollable cursor for which
the <i>cursor_orientation</i> parameter is set to
<i>PDO::FETCH_ORI_REL</i>, this value specifies the
row to fetch relative to the cursor position before
<b>PDOStatement::fetch()</b> was called.
</p>
</dd>
</dl>
<p>
</p>
</div>
<a name="pdostatement.fetch.returnvalues"></a><div class="refsect1 returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
The return value of this function on success depends on the fetch type. In
all cases, <b><tt class="constant">FALSE</tt></b> is returned on failure.
</p>
</div>
<a name="pdostatement.fetch.examples"></a><div class="refsect1 examples">
<h3 class="title">Examples</h3>
<p class="para">
</p><div class="example"><p><b>Example #1 Fetching rows using different fetch styles</b></p>
<div class="example-contents programlisting">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$sth </span><span style="color: #007700">= </span><span style="color: #0000BB">$dbh</span><span style="color: #007700">-></span><span style="color: #0000BB">prepare</span><span style="color: #007700">(</span><span style="color: #DD0000">"SELECT name, colour FROM fruit"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$sth</span><span style="color: #007700">-></span><span style="color: #0000BB">execute</span><span style="color: #007700">();<br /><br /></span><span style="color: #FF8000">/* Exercise PDOStatement::fetch styles */<br /></span><span style="color: #007700">print(</span><span style="color: #DD0000">"PDO::FETCH_ASSOC: "</span><span style="color: #007700">);<br />print(</span><span style="color: #DD0000">"Return next row as an array indexed by column name\n"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$result </span><span style="color: #007700">= </span><span style="color: #0000BB">$sth</span><span style="color: #007700">-></span><span style="color: #0000BB">fetch</span><span style="color: #007700">(</span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">FETCH_ASSOC</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$result</span><span style="color: #007700">);<br />print(</span><span style="color: #DD0000">"\n"</span><span style="color: #007700">);<br /><br />print(</span><span style="color: #DD0000">"PDO::FETCH_BOTH: "</span><span style="color: #007700">);<br />print(</span><span style="color: #DD0000">"Return next row as an array indexed by both column name and number\n"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$result </span><span style="color: #007700">= </span><span style="color: #0000BB">$sth</span><span style="color: #007700">-></span><span style="color: #0000BB">fetch</span><span style="color: #007700">(</span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">FETCH_BOTH</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$result</span><span style="color: #007700">);<br />print(</span><span style="color: #DD0000">"\n"</span><span style="color: #007700">);<br /><br />print(</span><span style="color: #DD0000">"PDO::FETCH_LAZY: "</span><span style="color: #007700">);<br />print(</span><span style="color: #DD0000">"Return next row as an anonymous object with column names as properties\n"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$result </span><span style="color: #007700">= </span><span style="color: #0000BB">$sth</span><span style="color: #007700">-></span><span style="color: #0000BB">fetch</span><span style="color: #007700">(</span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">FETCH_LAZY</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$result</span><span style="color: #007700">);<br />print(</span><span style="color: #DD0000">"\n"</span><span style="color: #007700">);<br /><br />print(</span><span style="color: #DD0000">"PDO::FETCH_OBJ: "</span><span style="color: #007700">);<br />print(</span><span style="color: #DD0000">"Return next row as an anonymous object with column names as properties\n"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$result </span><span style="color: #007700">= </span><span style="color: #0000BB">$sth</span><span style="color: #007700">-></span><span style="color: #0000BB">fetch</span><span style="color: #007700">(</span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">FETCH_OBJ</span><span style="color: #007700">);<br />print </span><span style="color: #0000BB">$result</span><span style="color: #007700">-></span><span style="color: #0000BB">NAME</span><span style="color: #007700">;<br />print(</span><span style="color: #DD0000">"\n"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents para"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
PDO::FETCH_ASSOC: Return next row as an array indexed by column name
Array
(
[NAME] => apple
[COLOUR] => red
)
PDO::FETCH_BOTH: Return next row as an array indexed by both column name and number
Array
(
[NAME] => banana
[0] => banana
[COLOUR] => yellow
[1] => yellow
)
PDO::FETCH_LAZY: Return next row as an anonymous object with column names as properties
PDORow Object
(
[NAME] => orange
[COLOUR] => orange
)
PDO::FETCH_OBJ: Return next row as an anonymous object with column names as properties
kiwi
</pre></div>
</div>
</div><p>
</p><div class="example"><p><b>Example #2 Fetching rows with a scrollable cursor</b></p>
<div class="example-contents programlisting">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">readDataForwards</span><span style="color: #007700">(</span><span style="color: #0000BB">$dbh</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$sql </span><span style="color: #007700">= </span><span style="color: #DD0000">'SELECT hand, won, bet FROM mynumbers ORDER BY BET'</span><span style="color: #007700">;<br /> try {<br /> </span><span style="color: #0000BB">$stmt </span><span style="color: #007700">= </span><span style="color: #0000BB">$dbh</span><span style="color: #007700">-></span><span style="color: #0000BB">prepare</span><span style="color: #007700">(</span><span style="color: #0000BB">$sql</span><span style="color: #007700">, array(</span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">ATTR_CURSOR </span><span style="color: #007700">=> </span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">CURSOR_SCROLL</span><span style="color: #007700">));<br /> </span><span style="color: #0000BB">$stmt</span><span style="color: #007700">-></span><span style="color: #0000BB">execute</span><span style="color: #007700">();<br /> while (</span><span style="color: #0000BB">$row </span><span style="color: #007700">= </span><span style="color: #0000BB">$stmt</span><span style="color: #007700">-></span><span style="color: #0000BB">fetch</span><span style="color: #007700">(</span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">FETCH_NUM</span><span style="color: #007700">, </span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">FETCH_ORI_NEXT</span><span style="color: #007700">)) {<br /> </span><span style="color: #0000BB">$data </span><span style="color: #007700">= </span><span style="color: #0000BB">$row</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">] . </span><span style="color: #DD0000">"\t" </span><span style="color: #007700">. </span><span style="color: #0000BB">$row</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">] . </span><span style="color: #DD0000">"\t" </span><span style="color: #007700">. </span><span style="color: #0000BB">$row</span><span style="color: #007700">[</span><span style="color: #0000BB">2</span><span style="color: #007700">] . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /> print </span><span style="color: #0000BB">$data</span><span style="color: #007700">;<br /> }<br /> </span><span style="color: #0000BB">$stmt </span><span style="color: #007700">= </span><span style="color: #0000BB">null</span><span style="color: #007700">;<br /> }<br /> catch (</span><span style="color: #0000BB">PDOException $e</span><span style="color: #007700">) {<br /> print </span><span style="color: #0000BB">$e</span><span style="color: #007700">-></span><span style="color: #0000BB">getMessage</span><span style="color: #007700">();<br /> }<br />}<br />function </span><span style="color: #0000BB">readDataBackwards</span><span style="color: #007700">(</span><span style="color: #0000BB">$dbh</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$sql </span><span style="color: #007700">= </span><span style="color: #DD0000">'SELECT hand, won, bet FROM mynumbers ORDER BY bet'</span><span style="color: #007700">;<br /> try {<br /> </span><span style="color: #0000BB">$stmt </span><span style="color: #007700">= </span><span style="color: #0000BB">$dbh</span><span style="color: #007700">-></span><span style="color: #0000BB">prepare</span><span style="color: #007700">(</span><span style="color: #0000BB">$sql</span><span style="color: #007700">, array(</span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">ATTR_CURSOR </span><span style="color: #007700">=> </span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">CURSOR_SCROLL</span><span style="color: #007700">));<br /> </span><span style="color: #0000BB">$stmt</span><span style="color: #007700">-></span><span style="color: #0000BB">execute</span><span style="color: #007700">();<br /> </span><span style="color: #0000BB">$row </span><span style="color: #007700">= </span><span style="color: #0000BB">$stmt</span><span style="color: #007700">-></span><span style="color: #0000BB">fetch</span><span style="color: #007700">(</span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">FETCH_NUM</span><span style="color: #007700">, </span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">FETCH_ORI_LAST</span><span style="color: #007700">);<br /> do {<br /> </span><span style="color: #0000BB">$data </span><span style="color: #007700">= </span><span style="color: #0000BB">$row</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">] . </span><span style="color: #DD0000">"\t" </span><span style="color: #007700">. </span><span style="color: #0000BB">$row</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">] . </span><span style="color: #DD0000">"\t" </span><span style="color: #007700">. </span><span style="color: #0000BB">$row</span><span style="color: #007700">[</span><span style="color: #0000BB">2</span><span style="color: #007700">] . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /> print </span><span style="color: #0000BB">$data</span><span style="color: #007700">;<br /> } while (</span><span style="color: #0000BB">$row </span><span style="color: #007700">= </span><span style="color: #0000BB">$stmt</span><span style="color: #007700">-></span><span style="color: #0000BB">fetch</span><span style="color: #007700">(</span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">FETCH_NUM</span><span style="color: #007700">, </span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">FETCH_ORI_PRIOR</span><span style="color: #007700">));<br /> </span><span style="color: #0000BB">$stmt </span><span style="color: #007700">= </span><span style="color: #0000BB">null</span><span style="color: #007700">;<br /> }<br /> catch (</span><span style="color: #0000BB">PDOException $e</span><span style="color: #007700">) {<br /> print </span><span style="color: #0000BB">$e</span><span style="color: #007700">-></span><span style="color: #0000BB">getMessage</span><span style="color: #007700">();<br /> }<br />}<br /><br />print </span><span style="color: #DD0000">"Reading forwards:\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">readDataForwards</span><span style="color: #007700">(</span><span style="color: #0000BB">$conn</span><span style="color: #007700">);<br /><br />print </span><span style="color: #DD0000">"Reading backwards:\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">readDataBackwards</span><span style="color: #007700">(</span><span style="color: #0000BB">$conn</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents para"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Reading forwards:
21 10 5
16 0 5
19 20 10
Reading backwards:
19 20 10
16 0 5
21 10 5
</pre></div>
</div>
</div><p>
</p>
</div>
<a name="pdostatement.fetch.seealso"></a><div class="refsect1 seealso">
<h3 class="title">See Also</h3>
<p class="para">
</p><ul class="simplelist">
<li class="member"><a href="pdo.prepare.php" class="function" rel="rdfs-seeAlso">PDO::prepare()</a> - Prepares a statement for execution and returns a statement object</li>
<li class="member"><a href="pdostatement.execute.php" class="function" rel="rdfs-seeAlso">PDOStatement::execute()</a> - Executes a prepared statement</li>
<li class="member"><a href="pdostatement.fetchall.php" class="function" rel="rdfs-seeAlso">PDOStatement::fetchAll()</a> - Returns an array containing all of the result set rows</li>
<li class="member"><a href="pdostatement.fetchcolumn.php" class="function" rel="rdfs-seeAlso">PDOStatement::fetchColumn()</a> - Returns a single column from the next row of a result set</li>
<li class="member"><a href="pdostatement.fetchobject.php" class="function" rel="rdfs-seeAlso">PDOStatement::fetchObject()</a> - Fetches the next row and returns it as an object.</li>
<li class="member"><a href="pdostatement.setfetchmode.php" class="function" rel="rdfs-seeAlso">PDOStatement::setFetchMode()</a> - Set the default fetch mode for this statement</li>
</ul><p>
</p>
</div>
</div><?php manual_footer(); ?>
