mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-28 23:08:55 +00:00
347 lines
11 KiB
XML
347 lines
11 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<refentry xml:id="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;
|
|
<methodsynopsis>
|
|
<modifier>public</modifier> <type>mixed</type><methodname>PDOStatement::fetch</methodname>
|
|
<methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer>PDO::FETCH_DEFAULT</initializer></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>cursorOrientation</parameter><initializer>PDO::FETCH_ORI_NEXT</initializer></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>cursorOffset</parameter><initializer>0</initializer></methodparam>
|
|
</methodsynopsis>
|
|
|
|
<para>
|
|
Fetches a row from a result set associated with a PDOStatement object. The
|
|
<parameter>mode</parameter> parameter determines how PDO returns
|
|
the row.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>mode</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 value of <literal>PDO::ATTR_DEFAULT_FETCH_MODE</literal>
|
|
(which defaults 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 <function>PDOStatement::bindColumn</function>
|
|
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, and calling the constructor afterwards, unless
|
|
<literal>PDO::FETCH_PROPS_LATE</literal> is also given.
|
|
If <parameter>mode</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_NAMED</literal>: returns an array with the same
|
|
form as <literal>PDO::FETCH_ASSOC</literal>, except that if there are
|
|
multiple columns with the same name, the value referred to by that
|
|
key will be an array of all the values in the row that had that
|
|
column name
|
|
</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>
|
|
<listitem><para>
|
|
<literal>PDO::FETCH_PROPS_LATE</literal>: when used with
|
|
<literal>PDO::FETCH_CLASS</literal>, the constructor of the class is
|
|
called before the properties are assigned from the respective column
|
|
values.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>cursorOrientation</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 <function>PDO::prepare</function>.
|
|
</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
|
|
<function>PDOStatement::fetch</function> 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';
|
|
$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;
|
|
}
|
|
}
|
|
function readDataBackwards($dbh) {
|
|
$sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
|
|
$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));
|
|
}
|
|
|
|
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>
|
|
|
|
<example><title>Construction order</title>
|
|
<simpara>
|
|
When objects are fetched via <literal>PDO::FETCH_CLASS</literal> the object
|
|
properties are assigned first, and then the constructor of the class is
|
|
invoked. If <literal>PDO::FETCH_PROPS_LATE</literal> is also given, this
|
|
order is reversed, i.e. first the constructor is called, and afterwards the
|
|
properties are assigned.
|
|
</simpara>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
class Person
|
|
{
|
|
private $name;
|
|
|
|
public function __construct()
|
|
{
|
|
$this->tell();
|
|
}
|
|
|
|
public function tell()
|
|
{
|
|
if (isset($this->name)) {
|
|
echo "I am {$this->name}.\n";
|
|
} else {
|
|
echo "I don't have a name yet.\n";
|
|
}
|
|
}
|
|
}
|
|
|
|
$sth = $dbh->query("SELECT * FROM people");
|
|
$sth->setFetchMode(PDO::FETCH_CLASS, 'Person');
|
|
$person = $sth->fetch();
|
|
$person->tell();
|
|
$sth->setFetchMode(PDO::FETCH_CLASS|PDO::FETCH_PROPS_LATE, 'Person');
|
|
$person = $sth->fetch();
|
|
$person->tell();
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs.similar;
|
|
<screen>
|
|
<![CDATA[
|
|
I am Alice.
|
|
I am Alice.
|
|
I don't have a name yet.
|
|
I am Bob.
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><function>PDO::prepare</function></member>
|
|
<member><function>PDOStatement::execute</function></member>
|
|
<member><function>PDOStatement::fetchAll</function></member>
|
|
<member><function>PDOStatement::fetchColumn</function></member>
|
|
<member><function>PDOStatement::fetchObject</function></member>
|
|
<member><function>PDOStatement::setFetchMode</function></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:"~/.phpdoc/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
|
|
-->
|