mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-26 22:08:55 +00:00
5feb6bbf6e
- Added return values section for completeness - Fixed up See Also section git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@242352 c90b9560-bf6c-de11-be94-00142212c4b1
297 lines
9.3 KiB
XML
297 lines
9.3 KiB
XML
<?xml version='1.0' encoding='iso-8859-1'?>
|
|
<!-- $Revision: 1.16 $ -->
|
|
<refentry xml:id="function.PDOStatement-fetch" xmlns="http://docbook.org/ns/docbook">
|
|
<refnamediv>
|
|
<refname>PDOStatement->fetch()</refname>
|
|
<refpurpose>
|
|
Fetches the next row from a result set
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<classsynopsis>
|
|
<ooclass><classname>PDOStatement</classname></ooclass>
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname>fetch</methodname>
|
|
<methodparam choice="opt"><type>int</type><parameter>fetch_style</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>cursor_orientation</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>cursor_offset</parameter></methodparam>
|
|
</methodsynopsis>
|
|
</classsynopsis>
|
|
|
|
<para>
|
|
Fetches a row from a result set associated with a PDOStatement object. The
|
|
<parameter>fetch_style</parameter> parameter determines how PDO returns
|
|
the row.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>fetch_style</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Controls how the next row will be returned to the caller. This value
|
|
must be one of the <literal>PDO::FETCH_*</literal> constants,
|
|
defaulting to <literal>PDO::FETCH_BOTH</literal>.
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<literal>PDO::FETCH_ASSOC</literal>: returns an array indexed by column
|
|
name as returned in your result set
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<literal>PDO::FETCH_BOTH</literal> (default): returns an array indexed by
|
|
both column name and 0-indexed column number as returned in your
|
|
result set
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<literal>PDO::FETCH_BOUND</literal>: returns &true; and assigns the
|
|
values of the columns in your result set to the PHP variables to which
|
|
they were bound with the <xref linkend="function.PDOStatement-bindColumn" />
|
|
method
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<literal>PDO::FETCH_CLASS</literal>: returns a new instance of the
|
|
requested class, mapping the columns of the result set to named
|
|
properties in the class. If <parameter>fetch_style</parameter>
|
|
includes PDO::FETCH_CLASSTYPE (e.g. <literal>PDO::FETCH_CLASS |
|
|
PDO::FETCH_CLASSTYPE</literal>) then the name of the class is
|
|
determined from a value of the first column.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<literal>PDO::FETCH_INTO</literal>: updates an existing instance
|
|
of the requested class, mapping the columns of the result set to
|
|
named properties in the class
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<literal>PDO::FETCH_LAZY</literal>: combines
|
|
<literal>PDO::FETCH_BOTH</literal> and <literal>PDO::FETCH_OBJ</literal>,
|
|
creating the object variable names as they are accessed
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<literal>PDO::FETCH_NUM</literal>: returns an array indexed by column
|
|
number as returned in your result set, starting at column 0
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<literal>PDO::FETCH_OBJ</literal>: returns an anonymous object with
|
|
property names that correspond to the column names returned in your
|
|
result set
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>cursor_orientation</parameter></term>
|
|
<listitem>
|
|
<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 <literal>PDO::FETCH_ORI_*</literal> constants,
|
|
defaulting to <literal>PDO::FETCH_ORI_NEXT</literal>. To request a
|
|
scrollable cursor for your PDOStatement object, you must set the
|
|
<literal>PDO::ATTR_CURSOR</literal> attribute to
|
|
<literal>PDO::CURSOR_SCROLL</literal> when you prepare the SQL
|
|
statement with <xref linkend="function.PDO-prepare" />.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>offset</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
For a PDOStatement object representing a scrollable cursor for which
|
|
the <literal>cursor_orientation</literal> parameter is set to
|
|
<literal>PDO::FETCH_ORI_ABS</literal>, this value specifies the
|
|
absolute number of the row in the result set that shall be fetched.
|
|
</para>
|
|
<para>
|
|
For a PDOStatement object representing a scrollable cursor for which
|
|
the <literal>cursor_orientation</literal> parameter is set to
|
|
<literal>PDO::FETCH_ORI_REL</literal>, this value specifies the
|
|
row to fetch relative to the cursor position before
|
|
<xref linkend="function.PDOStatement-fetch" /> was called.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
The return value of this function on success depends on the fetch type. In
|
|
all cases, &false; is returned on failure.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example><title>Fetching rows using different fetch styles</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$sth = $dbh->prepare("SELECT name, colour FROM fruit");
|
|
$sth->execute();
|
|
|
|
/* Exercise PDOStatement::fetch styles */
|
|
print("PDO::FETCH_ASSOC: ");
|
|
print("Return next row as an array indexed by column name\n");
|
|
$result = $sth->fetch(PDO::FETCH_ASSOC);
|
|
print_r($result);
|
|
print("\n");
|
|
|
|
print("PDO::FETCH_BOTH: ");
|
|
print("Return next row as an array indexed by both column name and number\n");
|
|
$result = $sth->fetch(PDO::FETCH_BOTH);
|
|
print_r($result);
|
|
print("\n");
|
|
|
|
print("PDO::FETCH_LAZY: ");
|
|
print("Return next row as an anonymous object with column names as properties\n");
|
|
$result = $sth->fetch(PDO::FETCH_LAZY);
|
|
print_r($result);
|
|
print("\n");
|
|
|
|
print("PDO::FETCH_OBJ: ");
|
|
print("Return next row as an anonymous object with column names as properties\n");
|
|
$result = $sth->fetch(PDO::FETCH_OBJ);
|
|
print $result->NAME;
|
|
print("\n");
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
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
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
<example><title>Fetching rows with a scrollable cursor</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
function readDataForwards($dbh) {
|
|
$sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY BET';
|
|
try {
|
|
$stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
|
|
$stmt->execute();
|
|
while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_NEXT)) {
|
|
$data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
|
|
print $data;
|
|
}
|
|
$stmt = null;
|
|
}
|
|
catch (PDOException $e) {
|
|
print $e->getMessage();
|
|
}
|
|
}
|
|
function readDataBackwards($dbh) {
|
|
$sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
|
|
try {
|
|
$stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
|
|
$stmt->execute();
|
|
$row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_LAST);
|
|
do {
|
|
$data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
|
|
print $data;
|
|
} while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_PRIOR));
|
|
$stmt = null;
|
|
}
|
|
catch (PDOException $e) {
|
|
print $e->getMessage();
|
|
}
|
|
}
|
|
|
|
print "Reading forwards:\n";
|
|
readDataForwards($conn);
|
|
|
|
print "Reading backwards:\n";
|
|
readDataBackwards($conn);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
Reading forwards:
|
|
21 10 5
|
|
16 0 5
|
|
19 20 10
|
|
|
|
Reading backwards:
|
|
19 20 10
|
|
16 0 5
|
|
21 10 5
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><xref linkend="function.PDO-prepare" /></member>
|
|
<member><xref linkend="function.PDOStatement-execute" /></member>
|
|
<member><xref linkend="function.PDOStatement-fetchAll" /></member>
|
|
<member><xref linkend="function.PDOStatement-fetchColumn" /></member>
|
|
<member><xref linkend="function.PDOStatement-fetchObject" /></member>
|
|
<member><xref linkend="function.PDOStatement-setFetchMode" /></member>
|
|
</simplelist>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../../../../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|