Author: Gina Peter Banyard (Girgias)
Committer: GitHub (web-flow)
Pusher: kamil-tekiela
Date: 2026-10-01T14:10:32+01:00
Commit: https://github.com/php/doc-en/commit/d312fb61f970ec50f4ce7cbaac90dc62e2d2a551
Raw diff: https://github.com/php/doc-en/commit/d312fb61f970ec50f4ce7cbaac90dc62e2d2a551.diff
Rewrite PDOStatement::fetch() docs (#5022)
Co-authored-by: Kamil Tekiela <tekiela246@gmail.com>
Co-authored-by: lacatoire <la.catoire@gmail.com>
Changed paths:
M reference/pdo/pdostatement/fetch.xml
Diff:
diff --git a/reference/pdo/pdostatement/fetch.xml b/reference/pdo/pdostatement/fetch.xml
index b1448079d58c..d222ed4917d9 100644
--- a/reference/pdo/pdostatement/fetch.xml
+++ b/reference/pdo/pdostatement/fetch.xml
@@ -16,156 +16,170 @@
<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>
+ <simpara>
+ Fetches a row from a result set associated with a
+ <classname>PDOStatement</classname> instance.
+ The <parameter>mode</parameter> parameter determines how PDO returns the row.
+ </simpara>
</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
<constant>PDO::FETCH_<replaceable>*</replaceable></constant> constants,
- defaulting to value of <constant>PDO::ATTR_DEFAULT_FETCH_MODE</constant>
- (which defaults to <constant>PDO::FETCH_BOTH</constant>).
- <itemizedlist>
- <listitem>
- <simpara>
- <constant>PDO::FETCH_ASSOC</constant>: returns an array indexed by column
- name as returned in your result set
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <constant>PDO::FETCH_BOTH</constant> (default): returns an array indexed by
- both column name and 0-indexed column number as returned in your
- result set
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <constant>PDO::FETCH_BOUND</constant>: returns &true; and assigns the
- values of the columns in your result set to the PHP variables to which
- they were bound with the <methodname>PDOStatement::bindColumn</methodname>
- method
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <constant>PDO::FETCH_CLASS</constant>: returns a new instance of the
- requested class. The object is initialized by mapping the columns of
- the result set to properties in the class. This occurs before the
- constructor is called, allowing properties to be populated regardless
- of their visibility or whether they are marked as
<literal>readonly</literal>.
- If a property does not exist in the class, the magic <link
linkend="object.set">__set()</link>
- method will be invoked if it exists; otherwise, a dynamic public
- property will be created. However, when
<constant>PDO::FETCH_PROPS_LATE</constant>
- is also given, the constructor is called <emphasis>before</emphasis>
- the properties are populated. If <parameter>mode</parameter> includes
- <constant>PDO::FETCH_CLASSTYPE</constant> (e.g.
- <literal>PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE</literal>), the name
- of the class is determined from the value of the first column.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <constant>PDO::FETCH_INTO</constant>: updates an existing instance
- of the requested class, mapping the columns of the result set to
- named properties in the class
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <constant>PDO::FETCH_LAZY</constant>: combines
- <constant>PDO::FETCH_BOTH</constant> and
<constant>PDO::FETCH_OBJ</constant>,
- and returns a <classname>PDORow</classname> object
- which creates the object property names as they are accessed.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <constant>PDO::FETCH_NAMED</constant>: returns an array with the same
- form as <constant>PDO::FETCH_ASSOC</constant>, 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
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <constant>PDO::FETCH_NUM</constant>: returns an array indexed by column
- number as returned in your result set, starting at column 0
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <constant>PDO::FETCH_OBJ</constant>: returns an anonymous object with
- property names that correspond to the column names returned in your
- result set
- </simpara>
- </listitem>
- <listitem>
+ <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
+ <constant>PDO::FETCH_<replaceable>*</replaceable></constant>
constants,
+ defaulting to value of <constant>PDO::ATTR_DEFAULT_FETCH_MODE</constant>
+ (which defaults to <constant>PDO::FETCH_BOTH</constant>).
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <constant>PDO::FETCH_ASSOC</constant>: returns an array indexed by
+ column name as returned in the result set.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <constant>PDO::FETCH_NAMED</constant>: returns an array with the same
+ form as <constant>PDO::FETCH_ASSOC</constant>,
+ 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.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <constant>PDO::FETCH_NUM</constant>: returns an array indexed by column
+ number as returned in the result set, starting at column 0.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <constant>PDO::FETCH_BOTH</constant>: returns an array indexed by
+ both column name and 0-indexed column number as returned in the
+ result set.
+ This is effectively a combination of
+ <constant>PDO::FETCH_NUM</constant> and
+ <constant>PDO::FETCH_ASSOC</constant>.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <constant>PDO::FETCH_BOUND</constant>: returns &true; and assigns
+ the values of the columns in the result set to the PHP variables to
+ which they were bound with the
+ <methodname>PDOStatement::bindColumn</methodname> method.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <constant>PDO::FETCH_OBJ</constant>: returns an instance of
+ <classname>stdClass</classname> with property names that correspond
+ to the column names returned in the result set.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <constant>PDO::FETCH_CLASS</constant>: returns a new instance of the
+ requested class. Unless the class was set with
+ <methodname>PDOStatement::setFetchMode</methodname>, this mode must be
+ combined with <constant>PDO::FETCH_CLASSTYPE</constant>, in which case
+ the class to instantiate is determined by the value of the
+ first column.
+ </simpara>
+ <simpara>
+ By default, the object is initialized by mapping the columns of
+ the result set to properties in the class.
+ This occurs <emphasis>prior</emphasis> to calling the constructor,
+ allowing properties to be populated regardless of their visibility
+ or whether they are marked as <literal>readonly</literal>, as long as
+ the constructor does not initialize them itself.
+
+ If a property does not exist in the class, the magic
+ <link linkend="object.set">__set()</link>
+ method will be invoked if it exists; otherwise, a dynamic public
+ property will be created.
+ </simpara>
+ <simpara>
+ It is possible to change this behaviour by using the
+ <constant>PDO::FETCH_PROPS_LATE</constant> flag to call the
+ constructor <emphasis>before</emphasis> the properties are populated.
+ </simpara>
+ <caution>
<simpara>
- <constant>PDO::FETCH_PROPS_LATE</constant>: when used with
- <constant>PDO::FETCH_CLASS</constant>, the constructor of the class is
- called before the properties are assigned from the respective column
- values.
+ The column values are <emphasis>not</emphasis> passed as arguments
+ to the constructor, regardless of whether
+ <constant>PDO::FETCH_PROPS_LATE</constant> is used. Only arguments given to
+ <methodname>PDOStatement::setFetchMode</methodname> are passed.
</simpara>
- </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
<constant>PDO::FETCH_ORI_<replaceable>*</replaceable></constant> constants,
- defaulting to <constant>PDO::FETCH_ORI_NEXT</constant>. To request a
- scrollable cursor for your PDOStatement object, you must set the
- <constant>PDO::ATTR_CURSOR</constant> attribute to
- <constant>PDO::CURSOR_SCROLL</constant> when you prepare the SQL
- statement with <methodname>PDO::prepare</methodname>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>cursorOffset</parameter></term>
- <listitem>
- <para>
- For a PDOStatement object representing a scrollable cursor for which
- the <parameter>cursorOrientation</parameter> parameter is set to
- <constant>PDO::FETCH_ORI_ABS</constant>, 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 <parameter>cursorOrientation</parameter> parameter is set to
- <constant>PDO::FETCH_ORI_REL</constant>, this value specifies the
- row to fetch relative to the cursor position before
- <methodname>PDOStatement::fetch</methodname> was called.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ </caution>
+ </listitem>
+ <listitem>
+ <simpara>
+ <constant>PDO::FETCH_INTO</constant>: updates an existing instance
+ of the requested class, mapping the columns of the result set to
+ named properties in the class.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <constant>PDO::FETCH_LAZY</constant>: combines
+ <constant>PDO::FETCH_BOTH</constant> and
+ <constant>PDO::FETCH_OBJ</constant>,
+ and returns a <classname>PDORow</classname> object
+ which creates the object property names as they are accessed.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cursorOrientation</parameter></term>
+ <listitem>
+ <simpara>
+ For a <classname>PDOStatement</classname> object representing a
+ scrollable cursor, this value determines which row will be returned
+ to the caller. This value must be one of the
+ <constant>PDO::FETCH_ORI_<replaceable>*</replaceable></constant>
+ constants, defaulting to <constant>PDO::FETCH_ORI_NEXT</constant>.
+ To request a scrollable cursor for the
+ <classname>PDOStatement</classname> object,
+ the <constant>PDO::ATTR_CURSOR</constant> attribute must be set to
+ <constant>PDO::CURSOR_SCROLL</constant> when the SQL statement is
+ prepared with <methodname>PDO::prepare</methodname>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cursorOffset</parameter></term>
+ <listitem>
+ <simpara>
+ If the value of the <parameter>cursorOrientation</parameter> parameter
+ is <constant>PDO::FETCH_ORI_ABS</constant>, this value specifies the
+ absolute number of the row in the result set that shall be fetched.
+ </simpara>
+ <simpara>
+ If the value of the <parameter>cursorOrientation</parameter> parameter
+ is <constant>PDO::FETCH_ORI_REL</constant>, this value specifies the
+ row to fetch relative to the cursor position before
+ <methodname>PDOStatement::fetch</methodname> was called.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
+ <simpara>
The return value of this function on success depends on the fetch type. In
all cases, &false; is returned on failure or if there are no more rows.
- </para>
+ </simpara>
</refsect1>
<refsect1 role="errors">
@@ -175,74 +189,95 @@
<refsect1 role="examples">
&reftitle.examples;
- <para>
- <example><title>Fetching rows using different fetch styles</title>
- <programlisting role="php">
+ <example>
+ <title>Fetching rows using different fetch styles</title>
+ <programlisting role="php">
<![CDATA[
<?php
-$sth = $dbh->prepare("SELECT name, colour FROM fruit");
+$db = new PDO('sqlite::memory:');
+$db->exec("CREATE TABLE fruit (name VARCHAR(100), colour VARCHAR(100))");
+$db->exec("INSERT INTO fruit (name, colour) VALUES
+ ('apple', 'red'),
+ ('banana', 'yellow'),
+ ('orange', 'orange'),
+ ('kiwi', 'green')");
+$sth = $db->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";
+echo "PDO::FETCH_ASSOC: ";
+echo "Return next row as an array indexed by column name\n";
$result = $sth->fetch(PDO::FETCH_ASSOC);
-print_r($result);
-print "\n";
+var_dump($result);
+echo "\n";
-print "PDO::FETCH_BOTH: ";
-print "Return next row as an array indexed by both column name and number\n";
+echo "PDO::FETCH_BOTH: ";
+echo "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";
+var_dump($result);
+echo "\n";
-print "PDO::FETCH_LAZY: ";
-print "Return next row as a PDORow object with column names as properties\n";
+echo "PDO::FETCH_LAZY: ";
+echo "Return next row as a PDORow object with column names as properties\n";
$result = $sth->fetch(PDO::FETCH_LAZY);
-print_r($result);
-print "\n";
+var_dump($result);
+echo "\n";
-print "PDO::FETCH_OBJ: ";
-print "Return next row as an anonymous object with column names as properties\n";
+echo "PDO::FETCH_OBJ: ";
+echo "Return next row as an stdClass object with column names as properties\n";
$result = $sth->fetch(PDO::FETCH_OBJ);
-print $result->name;
-print "\n";
+var_dump($result);
+echo "\n";
?>
]]>
- </programlisting>
- &example.outputs;
- <screen>
+ </programlisting>
+ &example.outputs;
+ <screen>
<![CDATA[
PDO::FETCH_ASSOC: Return next row as an array indexed by column name
-Array
-(
- [name] => apple
- [colour] => red
-)
+array(2) {
+ ["name"]=>
+ string(5) "apple"
+ ["colour"]=>
+ string(3) "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
-)
+array(4) {
+ ["name"]=>
+ string(6) "banana"
+ [0]=>
+ string(6) "banana"
+ ["colour"]=>
+ string(6) "yellow"
+ [1]=>
+ string(6) "yellow"
+}
PDO::FETCH_LAZY: Return next row as a PDORow object with column names as properties
-PDORow Object
-(
- [name] => orange
- [colour] => orange
-)
+object(PDORow)#3 (3) {
+ ["queryString"]=>
+ string(30) "SELECT name, colour FROM fruit"
+ ["name"]=>
+ string(6) "orange"
+ ["colour"]=>
+ string(6) "orange"
+}
+
+PDO::FETCH_OBJ: Return next row as an stdClass object with column names as properties
+object(stdClass)#4 (2) {
+ ["name"]=>
+ string(4) "kiwi"
+ ["colour"]=>
+ string(5) "green"
+}
-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">
+ </screen>
+ </example>
+ <example>
+ <title>Fetching rows with a scrollable cursor</title>
+ <programlisting role="php">
<![CDATA[
<?php
function readDataForwards($dbh) {
@@ -272,9 +307,9 @@ print "Reading backwards:\n";
readDataBackwards($conn);
?>
]]>
- </programlisting>
- &example.outputs;
- <screen>
+ </programlisting>
+ &example.outputs;
+ <screen>
<![CDATA[
Reading forwards:
21 10 5
@@ -286,18 +321,19 @@ Reading backwards:
16 0 5
21 10 5
]]>
- </screen>
- </example>
+ </screen>
+ </example>
- <example><title>Construction order</title>
- <simpara>
- When objects are fetched via <constant>PDO::FETCH_CLASS</constant>, the object
- properties are assigned first, and then the constructor of the class is
- invoked. However, when <constant>PDO::FETCH_PROPS_LATE</constant> is also given,
- this order is reversed, i.e. first the constructor is called, and
- afterwards the properties are assigned.
- </simpara>
- <programlisting role="php">
+ <example>
+ <title>Construction order</title>
+ <simpara>
+ When objects are fetched via <constant>PDO::FETCH_CLASS</constant>, the object
+ properties are assigned first, and then the constructor of the class is
+ invoked. However, when <constant>PDO::FETCH_PROPS_LATE</constant> 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
@@ -328,32 +364,29 @@ $person = $sth->fetch();
$person->tell();
?>
]]>
- </programlisting>
- &example.outputs.similar;
- <screen>
+ </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>
+ </screen>
+ </example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
- <member><methodname>PDO::prepare</methodname></member>
- <member><methodname>PDOStatement::execute</methodname></member>
- <member><methodname>PDOStatement::fetchAll</methodname></member>
- <member><methodname>PDOStatement::fetchColumn</methodname></member>
- <member><methodname>PDOStatement::fetchObject</methodname></member>
- <member><methodname>PDOStatement::setFetchMode</methodname></member>
- </simplelist>
- </para>
+ <simplelist>
+ <member><methodname>PDO::prepare</methodname></member>
+ <member><methodname>PDOStatement::execute</methodname></member>
+ <member><methodname>PDOStatement::fetchAll</methodname></member>
+ <member><methodname>PDOStatement::fetchColumn</methodname></member>
+ <member><methodname>PDOStatement::fetchObject</methodname></member>
+ <member><methodname>PDOStatement::setFetchMode</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file