[DOC-CVS] [doc-en] master: PDO Fetch Modes (#4936)
[email protected] (AllenJB via GitHub)
| Newsgroups | php.doc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: AllenJB (AllenJB)
Committer: GitHub (web-flow)
Pusher: kamil-tekiela
Date: 2025-11-03T12:58:41Z
Commit: https://github.com/php/doc-en/commit/812ed835faa11b611c112d2a16777aebf70eb020
Raw diff: https://github.com/php/doc-en/commit/812ed835faa11b611c112d2a16777aebf70eb020.diff
PDO Fetch Modes (#4936)
Changed paths:
A reference/pdo/constants.fetch-modes.xml
M reference/pdo/constants.xml
M reference/pdo/pdorow.xml
Diff:
diff --git a/reference/pdo/constants.fetch-modes.xml b/reference/pdo/constants.fetch-modes.xml
new file mode 100644
index 000000000000..aef9b257f0c2
--- /dev/null
+++ b/reference/pdo/constants.fetch-modes.xml
@@ -0,0 +1,1455 @@
+<?xml version="1.0" encoding="utf-8"?>
+<section xmlns="http://docbook.org/ns/docbook" xml:id="pdo.constants.fetch-modes">
+ <title>Fetch Modes</title>
+
+ <para>
+ See <link linkend="pdo.constants.cursors">cursor constants</link> for the
+ <literal>PDO::FETCH_ORI_*</literal> cursor constants.
+ </para>
+
+ <section xml:id="pdo.fetch-modes.basic" annotations="chunk:false">
+ <title>Basic Fetch Modes</title>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Fetch Mode</entry>
+ <entry>Summary</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_DEFAULT</constant>
+ </entry>
+ <entry>
+ Special value for using the current default fetch mode.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_ASSOC</constant>
+ </entry>
+ <entry>
+ Array indexed by column name only.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_BOTH</constant> (Default)
+ </entry>
+ <entry>
+ Array indexed by both column number and name.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_NAMED</constant>
+ </entry>
+ <entry>
+ Variant of <constant>PDO::FETCH_ASSOC</constant> that retains duplicated
+ columns.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_NUM</constant>
+ </entry>
+ <entry>
+ Array indexed by column number only.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_COLUMN</constant>
+ </entry>
+ <entry>
+ A single column.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_KEY_PAIR</constant>
+ </entry>
+ <entry>
+ Key-value pairs, indexed by the first column.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_FUNC</constant>
+ </entry>
+ <entry>
+ Use a function to create the return value.
+ (<function>PDOStatement::fetchAll</function> only)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_OBJ</constant>
+ </entry>
+ <entry>
+ Anonymous (<classname>stdClass</classname>) object.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_CLASS</constant>
+ </entry>
+ <entry>
+ An object of a specified class.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section xml:id="pdo.fetch-modes.class-flags" annotations="chunk:false">
+ <title>PDO::FETCH_CLASS options</title>
+
+ <para>
+ These modes are used to implement options when using
+ <constant>PDO::FETCH_CLASS</constant>.
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Fetch Mode</entry>
+ <entry>Summary</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_CLASSTYPE</constant>
+ </entry>
+ <entry>
+ Use the first column as the class name.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_PROPS_LATE</constant>
+ </entry>
+ <entry>
+ Call the constructor before setting properties.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_SERIALIZE</constant>
+ </entry>
+ <entry>
+ Use PHP serialized data. Deprecated as of PHP 8.1.0.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section xml:id="pdo.fetch-modes.single" annotations="chunk:false">
+ <title>Single Result Modes</title>
+
+ <para>
+ The following modes cannot be used with
+ <function>PDOStatement::fetchAll</function>.
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Fetch Mode</entry>
+ <entry>Summary</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_BOUND</constant>
+ </entry>
+ <entry>
+ Bind values to specified variables.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_INTO</constant>
+ </entry>
+ <entry>
+ Update an existing object.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_LAZY</constant>
+ </entry>
+ <entry>
+ Lazy fetch via <classname>PDORow</classname> for array- and object-like
+ access.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section xml:id="pdo.fetch-modes.grouped" annotations="chunk:false">
+ <title>
+ Special Behavior Flags for <function>PDOStatement::fetchAll</function>
+ </title>
+
+ <para>
+ The following special modes for multiple results only work with
+ <function>PDOStatement::fetchAll</function> and do not work with some other
+ fetch modes. Check the full documentation for details.
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Fetch Mode</entry>
+ <entry>Summary</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_GROUP</constant>
+ </entry>
+ <entry>
+ Results are grouped by the first column.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>PDO::FETCH_UNIQUE</constant>
+ </entry>
+ <entry>
+ Results are (uniquely) indexed by the first column.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section xml:id="pdo.fetch-modes.duplicate-names" annotations="chunk:false">
+ <title>Handling of Duplicated Column Names</title>
+ <para>
+ It's possible for results to contain multiple columns that use the same name.
+ For example, when joining 2 tables that both contain a column with the same
+ name.
+ </para>
+ <para>
+ Because PHP structures such as arrays and objects don't support multiple keys
+ or properties that use the same name, the returned array or object will
+ contain only 1 of the values using the same name.
+ </para>
+ <para>
+ Which value is returned for a given duplicated name should be considered
+ undefined.
+ </para>
+ <para>
+ To avoid this issue, explicitly name columns using an alias. For example:
+ </para>
+ <informalexample>
+ <programlisting role="sql">
+<![CDATA[
+SELECT table1.created_at AS t1_created_at,
+ table2.created_at AS t2_created_at
+FROM table1
+JOIN table2 ON table1.table2id = table2.id
+]]>
+ </programlisting>
+ </informalexample>
+ <para>
+ See also <constant>PDO::FETCH_NAMED</constant>,
+ <constant>PDO::ATTR_FETCH_TABLE_NAMES</constant> and
+ <constant>PDO::ATTR_FETCH_CATALOG_NAMES</constant>.
+ </para>
+ </section>
+
+ <section xml:id="pdo.fetch-modes.default" annotations="chunk:false">
+ <title>Setting the Default Fetch Mode</title>
+ <para>
+ You can set the default fetch mode for all queries using
+ <constant>PDO::ATTR_DEFAULT_FETCH_MODE</constant> with
+ <function>PDO::__construct</function> or
+ <function>PDO::setAttribute</function>.
+ </para>
+ <para>
+ You can set the default fetch mode for a specific statement using
+ <function>PDOStatement::setFetchMode</function>. This affects reuse as a
+ prepared statement and iteration (using
+ <link linkend="control-structures.foreach">foreach</link>).
+ </para>
+ <caution>
+ <para>
+ <function>PDOStatement::setAttribute</function> cannot be used to set the
+ default fetch mode. It only accepts driver specific attributes and silently
+ ignores attributes that are not recognized.
+ </para>
+ </caution>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-default" annotations="chunk:false">
+ <title>PDO::FETCH_DEFAULT (<type>int</type>)</title>
+ <para>
+ Available since PHP 8.0.7.
+ </para>
+ <para>
+ This is a special value that uses the current default fetch mode for a
+ <classname>PDOStatement</classname>. It's specifically useful as the default
+ value for method parameters when extending
+ <classname>PDOStatement</classname> for use with
+ <constant>PDO::ATTR_STATEMENT_CLASS</constant>.
+ </para>
+ <para>
+ This value cannot be used with
+ <constant>PDO::ATTR_DEFAULT_FETCH_MODE</constant>.
+ </para>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-assoc" annotations="chunk:false">
+ <title>PDO::FETCH_ASSOC (<type>int</type>)</title>
+ <para>
+ <constant>PDO::FETCH_ASSOC</constant> returns an array indexed by column name
+ only.
+ </para>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$stmt = $pdo->query("SELECT userid, name, country FROM users");
+$row = $stmt->fetch(\PDO::FETCH_ASSOC);
+print_r($row);
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Array
+(
+ [userid] => 104
+ [name] => Chris
+ [country] => Ukraine
+)
+]]>
+ </screen>
+ </informalexample>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-both" annotations="chunk:false">
+ <title>PDO::FETCH_BOTH (<type>int</type>)</title>
+ <para>
+ This is the default fetch mode.
+ </para>
+ <para>
+ <constant>PDO::FETCH_BOTH</constant> returns an array indexed by both column
+ number and name. This means that every returned value is duplicated for each
+ result row.
+ </para>
+ <para>
+ The column number starts at 0 and is determined by the result column order in
+ the query, not (for example) the order columns are defined in the table.
+ </para>
+ <note>
+ <para>
+ Using the numeric column index is not recommended as this may change when
+ the query is changed, or when the table schema is changed when using
+ <literal>SELECT *</literal>.
+ </para>
+ </note>
+ <note>
+ <para>
+ The number of entries indexed by name may not match the number of entries
+ indexed by number in cases where multiple returned columns use the same
+ name.
+ </para>
+ </note>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$stmt = $pdo->query("SELECT userid, name, country FROM users");
+$row = $stmt->fetch(\PDO::FETCH_BOTH);
+print_r($row);
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Array
+(
+ [id] => 104,
+ [0] => 104,
+ [name] => Chris,
+ [1] => Chris,
+ [country] => Ukraine,
+ [2] => Ukraine
+)
+]]>
+ </screen>
+ </informalexample>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-named" annotations="chunk:false">
+ <title>PDO::FETCH_NAMED (<type>int</type>)</title>
+ <para>
+ <constant>PDO::FETCH_NAMED</constant> returns results in the same format as
+ <constant>PDO::FETCH_ASSOC</constant> except that where multiple columns use
+ the same name, all values are returned as a list.
+ </para>
+ <para>
+ For more information on handling of duplicated column names and alternatives,
+ see the <link linkend="pdo.fetch-modes.duplicate-names">handling of
+ duplicated names section</link> above.
+ </para>
+ <para>
+ The order in which duplicated values are returned should be considered
+ undefined. There's no way to tell where each value came from.
+ </para>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$stmt = $pdo->query(
+ "SELECT users.*, referrer.name
+ FROM users
+ LEFT JOIN users AS referrer ON users.referred_by = referrer.userid
+ WHERE userid = 109"
+);
+$row = $stmt->fetch(\PDO::FETCH_NUM);
+print_r($row);
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Array
+(
+ [userid] => 109
+ [name] => Array
+ (
+ [0] => Toni
+ [1] => Chris
+ )
+ [country] => Germany
+ [referred_by] = 104
+)
+]]>
+ </screen>
+ </informalexample>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-num" annotations="chunk:false">
+ <title>PDO::FETCH_NUM (<type>int</type>)</title>
+ <para>
+ <constant>PDO::FETCH_NUM</constant> returns an array indexed by column number
+ only. The column number starts at 0 and is determined by the result column order in
+ the query, not (for example) the order columns are defined in the table.
+ </para>
+ <note>
+ <para>
+ Using the numeric column index is not recommended as this may change when
+ the query is changed, or when the table schema is changed when using
+ <literal>SELECT *</literal>.
+ </para>
+ </note>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$stmt = $pdo->query("SELECT userid, name, country FROM users");
+$row = $stmt->fetch(\PDO::FETCH_NUM);
+print_r($row);
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Array
+(
+ [0] => 104
+ [1] => Chris
+ [2] => Ukraine
+)
+]]>
+ </screen>
+ </informalexample>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-column" annotations="chunk:false">
+ <title>PDO::FETCH_COLUMN (<type>int</type>)</title>
+ <para>
+ <constant>PDO::FETCH_COLUMN</constant> returns values from a single column.
+ Use the second argument for <function>PDOStatement::setFetchMode</function>
+ or <function>PDOStatement::fetchAll</function> to specify which column is
+ returned.
+ </para>
+ <para>
+ If the specified column does not exist a <classname>ValueError</classname>
+ will be thrown.
+ </para>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
+$row = $stmt->fetchAll(\PDO::FETCH_COLUMN);
+print_r($row);
+
+$stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
+$row = $stmt->fetchAll(\PDO::FETCH_COLUMN, 1);
+print_r($row);
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Array
+(
+ [0] => Chris
+ [1] => Jamie
+ [2] => Robin
+)
+
+Array
+(
+ [0] => Ukraine
+ [1] => England
+ [2] => Germany
+)
+]]>
+ </screen>
+ </informalexample>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-key-pair" annotations="chunk:false">
+ <title>PDO::FETCH_KEY_PAIR (<type>int</type>)</title>
+ <para>
+ <constant>PDO::FETCH_KEY_PAIR</constant> returns pairs of values, indexed by
+ the first column. The results must contain only 2 columns. This fetch mode
+ only makes sense with <function>PDOStatement::fetchAll</function>.
+ </para>
+ <note>
+ <para>
+ If the first column is not unique, values will be lost. Which value(s) are
+ lost should be considered undefined.
+ </para>
+ </note>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
+$row = $stmt->fetchAll(\PDO::FETCH_KEY_PAIR);
+print_r($row);
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Array
+(
+ [Chris] => Ukraine
+ [Jamie] => England
+ [Robin] => Germany
+)
+]]>
+ </screen>
+ </informalexample>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-func" annotations="chunk:false">
+ <title>PDO::FETCH_FUNC (<type>int</type>)</title>
+ <para>
+ Specify a function to create the returned value. This mode can only be used
+ with <function>PDOStatement::fetchAll</function>.
+ </para>
+ <para>
+ The function receives the values as parameters. There's no way to retrieve
+ the column name a given value was associated with. You must make sure the
+ column order in the query matches that expected by the function.
+ </para>
+ <note>
+ <para>
+ The effects of <constant>PDO::FETCH_GROUP</constant> and
+ <constant>PDO::FETCH_UNIQUE</constant> are applied to results before the
+ function is called.
+ </para>
+ </note>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+function valueCreator($col1, $col2, $col3)
+{
+ return [
+ 'col1' => $col1,
+ 'col2' => strtoupper($col2),
+ 'col3' => $col3,
+ 'customKey' => 'customValue',
+ ];
+}
+
+$stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
+$row = $stmt->fetchAll(\PDO::FETCH_FUNC, valueCreator(...));
+print_r($row);
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Array
+(
+ [0] => Array
+ (
+ [col1] => 104
+ [col2] => SAM
+ [col3] => Ukraine
+ [customKey] => customValue
+ )
+
+ [1] => Array
+ (
+ [col1] => 105
+ [col2] => JAMIE
+ [col3] => England
+ [customKey] => customValue
+ )
+
+ [2] => Array
+ (
+ [col1] => 107
+ [col2] => ROBIN
+ [col3] => Germany
+ [customKey] => customValue
+ )
+
+)
+]]>
+ </screen>
+ </informalexample>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-obj" annotations="chunk:false">
+ <title>PDO::FETCH_OBJ (<type>int</type>)</title>
+ <para>
+ <constant>PDO::FETCH_OBJ</constant> returns a <classname>stdClass</classname>
+ object.
+ </para>
+ <para>
+ See also <function>PDOStatement::fetchObject</function> and
+ <constant>PDO::FETCH_CLASS</constant>.
+ </para>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$stmt = $pdo->query("SELECT userid, name, country FROM users");
+$row = $stmt->fetch(\PDO::FETCH_OBJ);
+print_r($row);
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+stdClass Object
+(
+ [userid] => 104
+ [name] => Chris
+ [country] => Ukraine
+)
+]]>
+ </screen>
+ </informalexample>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-class" annotations="chunk:false">
+ <title>PDO::FETCH_CLASS (<type>int</type>)</title>
+ <para>
+ Returns an object of a specified class. For additional behaviors see the
+ <link linkend="pdo.fetch-modes.class-flags">option flags</link>.
+ </para>
+ <para>
+ If a property does not exist with the name of a returned column, it will be
+ dynamically declared. This behavior is deprecated and will cause an error
+ from PHP 9.0.
+ </para>
+ <para>
+ See also <function>PDOStatement::fetchObject</function>.
+ </para>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+class TestEntity
+{
+ public $userid;
+
+ public $name;
+
+ public $country;
+
+ public $referred_by_userid;
+
+ public function __construct()
+ {
+ print "Constructor called with ". count(func_get_args()) ." args\n";
+ print "Properties set when constructor called? "
+ . (isset($this->name) ? 'Yes' : 'No') . "\n";
+ }
+}
+
+$stmt = $db->query(
+ "SELECT userid, name, country, referred_by_userid FROM users"
+);
+$stmt->setFetchMode(PDO::FETCH_CLASS, TestEntity::class);
+$result = $stmt->fetch();
+var_dump($result);
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+Constructor called with 0 args
+Properties set when constructor called? Yes
+object(TestEntity)#3 (4) {
+ ["userid"]=>
+ int(104)
+ ["name"]=>
+ string(5) "Chris"
+ ["country"]=>
+ string(7) "Ukraine"
+ ["referred_by_userid"]=>
+ NULL
+}
+]]>
+ </screen>
+ </informalexample>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-classtype" annotations="chunk:false">
+ <title>PDO::FETCH_CLASSTYPE (<type>int</type>)</title>
+ <para>
+ This fetch mode can only be used combined with
+ <constant>PDO::FETCH_CLASS</constant> (and
+ <link linkend="pdo.fetch-modes.class-flags">its other options</link>).
+ </para>
+ <para>
+ When this fetch mode is used, PDO will use the first returned column as the
+ name of the class to return.
+ </para>
+ <para>
+ If the specified class cannot be found, a <classname>stdClass</classname>
+ object will be returned, without warning or error.
+ </para>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+class TestEntity
+{
+ public $userid;
+
+ public $name;
+
+ public $country;
+
+ public $referred_by_userid;
+
+ public function __construct()
+ {
+ print "Constructor called with ". count(func_get_args()) ." args\n";
+ print "Properties set when constructor called? "
+ . (isset($this->name) ? 'Yes' : 'No') . "\n";
+ }
+}
+
+$stmt = $db->query(
+ "SELECT 'TestEntity', userid, name, country, referred_by_userid FROM users"
+);
+$stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE);
+$result = $stmt->fetch();
+var_dump($result);
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+Constructor called with 0 args
+Properties set when constructor called? Yes
+object(TestEntity)#3 (4) {
+ ["userid"]=>
+ int(104)
+ ["name"]=>
+ string(5) "Chris"
+ ["country"]=>
+ string(7) "Ukraine"
+ ["referred_by_userid"]=>
+ NULL
+}
+]]>
+ </screen>
+ </informalexample>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-props-late" annotations="chunk:false">
+ <title>PDO::FETCH_PROPS_LATE (<type>int</type>)</title>
+ <para>
+ This fetch mode can only be used combined with
+ <constant>PDO::FETCH_CLASS</constant> (and
+ <link linkend="pdo.fetch-modes.class-flags">its other options</link>).
+ </para>
+ <para>
+ When this fetch mode is used, the constructor will be called before the
+ properties are set.
+ </para>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+class TestEntity
+{
+ public $userid;
+
+ public $name;
+
+ public $country;
+
+ public $referred_by_userid;
+
+ public function __construct()
+ {
+ print "Constructor called with ". count(func_get_args()) ." args\n";
+ print "Properties set when constructor called? "
+ . (isset($this->name) ? 'Yes' : 'No') . "\n";
+ }
+}
+
+$stmt = $db->query(
+ "SELECT userid, name, country, referred_by_userid FROM users"
+);
+$stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, TestEntity::class);
+$result = $stmt->fetch();
+var_dump($result);
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+Constructor called with 0 args
+Properties set when constructor called? No
+object(TestEntity)#3 (4) {
+ ["userid"]=>
+ int(104)
+ ["name"]=>
+ string(5) "Chris"
+ ["country"]=>
+ string(7) "Ukraine"
+ ["referred_by_userid"]=>
+ NULL
+}
+]]>
+ </screen>
+ </informalexample>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-serialize" annotations="chunk:false">
+ <title>PDO::FETCH_SERIALIZE (<type>int</type>)</title>
+ <warning>
+ <simpara>
+ This feature has been <emphasis>DEPRECATED</emphasis> as of PHP 8.1.0.
+ Relying on this feature is highly discouraged.
+ </simpara>
+ </warning>
+ <para>
+ This fetch mode can only be used combined with
+ <constant>PDO::FETCH_CLASS</constant> (and
+ <link linkend="pdo.fetch-modes.class-flags">its other options</link>).
+ </para>
+ <para>
+ When this fetch mode is used, the specified class must be
+ <interfacename>Serializable</interfacename>.
+ </para>
+ <caution>
+ <para>
+ This feature does not support a string that contains a complete serialized
+ object (with <function>serialize</function>).
+ </para>
+ </caution>
+ <caution>
+ <para>
+ This fetch mode does not call the constructor.
+ </para>
+ </caution>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+class TestEntity implements Serializable
+{
+ public $userid;
+
+ public $name;
+
+ public $country;
+
+ public $referred_by_userid;
+
+ public function __construct()
+ {
+ print "Constructor called with " . count(func_get_args()) . " args\n";
+ print "Properties set when constructor called? "
+ . (isset($this->name) ? 'Yes' : 'No') . "\n";
+ }
+
+ public function serialize() {
+ return join(
+ "|",
+ [$this->userid, $this->name, $this->country, $this->referred_by_userid]
+ );
+ }
+
+ public function unserialize(string $data) {
+ $parts = explode("|", $data);
+ $this->userid = (int) $parts[0];
+ $this->name = $parts[1];
+ $this->country = $parts[2];
+
+ $refId = $parts[3];
+ $this->referred_by_userid = ($refId === "" ? null : (int) $refId);
+ }
+}
+
+print "Set up record (constructor called manually):\n";
+$db->exec(
+ "CREATE TABLE serialize (
+ sdata TEXT
+ )"
+);
+
+$origObj = new TestEntity();
+$origObj->userid = 200;
+$origObj->name = 'Seri';
+$origObj->country = 'Syria';
+$origObj->referred_by_userid = null;
+
+$insert = $db->prepare("INSERT INTO serialize (sdata) VALUES (:sdata)");
+$insert->execute(['sdata' => $origObj->serialize()]);
+
+print "\nRetrieve result:\n"
+$query = "SELECT sdata FROM serialize";
+$stmt = $db->query($query);
+// NOTE: Constructor is never called!
+$stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_SERIALIZE, TestEntity::class);
+$result = $stmt->fetch();
+var_dump($result);
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+Deprecated: TestEntity implements the Serializable interface, which is deprecated. Implement __serialize() and __unserialize() instead (or in addition, if support for old PHP versions is necessary) in Standard input code on line 2
+Set up record (constructor called manually):
+Constructor called with 0 args
+Properties set when constructor called? No
+
+Retrieve result:
+Deprecated: PDOStatement::setFetchMode(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 58
+
+Deprecated: PDOStatement::fetch(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 59
+object(TestEntity)#5 (4) {
+ ["userid"]=>
+ int(200)
+ ["name"]=>
+ string(4) "Seri"
+ ["country"]=>
+ string(5) "Syria"
+ ["referred_by_userid"]=>
+ NULL
+}
+]]>
+ </screen>
+ </informalexample>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-bound" annotations="chunk:false">
+ <title>PDO::FETCH_BOUND (<type>int</type>)</title>
+ <para>
+ This fetch mode cannot be used with
+ <function>PDOStatement::fetchAll</function>.
+ </para>
+ <para>
+ This fetch mode does not directly return a result, but binds values to
+ variables specified with <function>PDOStatement::bindColumn</function>. The
+ called fetch method returns &true;.
+ </para>
+ <note>
+ <para>
+ When using prepared statements, to work correctly, variables must be bound
+ after the query is executed.
+ </para>
+ </note>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$query = "SELECT users.userid, users.name, users.country, referrer.name
+ FROM users
+ LEFT JOIN users AS referrer ON users.referred_by_userid = referrer.userid";
+$stmt = $db->prepare($query);
+$stmt->execute();
+
+$stmt->bindColumn('userid', $userId);
+$stmt->bindColumn('name', $name);
+$stmt->bindColumn('country', $country);
+// Bind by column position to resolve duplicated column name
+// To avoid this breaking if the query is changed, use an SQL alias instead
+// For example: referrer.name AS referrer_name
+$stmt->bindColumn(4, $referrerName);
+
+print "\nfetch:\n";
+while ($stmt->fetch(\PDO::FETCH_BOUND)) {
+ print join("\t", [$userId, $name, $country, ($referrerName ?? 'NULL')]) . "\n";
+}
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+104 Chris Ukraine NULL
+105 Jamie England NULL
+107 Robin Germany Chris
+108 Sean Ukraine NULL
+109 Toni Germany NULL
+110 Toni Germany NULL
+]]>
+ </screen>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-into" annotations="chunk:false">
+ <title>PDO::FETCH_INTO (<type>int</type>)</title>
+ <para>
+ This fetch mode cannot be used with
+ <function>PDOStatement::fetchAll</function>.
+ </para>
+ <para>
+ This fetch mode updates properties in the specified object. The object is
+ returned on success.
+ </para>
+ <para>
+ If a property does not exist with the name of a returned column, it will be
+ dynamically declared. This behavior is deprecated and will cause an error
+ from PHP 9.0.
+ </para>
+ <para>
+ Properties must be <literal>public</literal> and cannot be
+ <literal>readonly</literal>.
+ </para>
+ <caution>
+ <para>
+ There's no way to change the object to be updated without using
+ <function>PDOStatement::setFetchMode</function> between retrieving each
+ record.
+ </para>
+ </caution>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+class TestEntity
+{
+ public $userid;
+
+ public $name;
+
+ public $country;
+
+ public $referred_by_userid;
+}
+
+$obj = new TestEntity();
+$stmt->setFetchMode(\PDO::FETCH_INTO, $obj);
+
+$stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");
+$result = $stmt->fetch();
+var_dump($result);
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+object(TestEntity)#3 (4) {
+ ["userid"]=>
+ int(104)
+ ["name"]=>
+ string(5) "Chris"
+ ["country"]=>
+ string(7) "Ukraine"
+ ["referred_by_userid"]=>
+ NULL
+}
+]]>
+ </screen>
+ </informalexample>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-lazy" annotations="chunk:false">
+ <title>PDO::FETCH_LAZY (<type>int</type>)</title>
+ <para>
+ This fetch mode cannot be used with
+ <function>PDOStatement::fetchAll</function>.
+ </para>
+ <para>
+ This fetch mode returns a <classname>PDORow</classname> object which provides
+ both array- and object-like access to values (i.e. combines the behavior of
+ <constant>PDO::FETCH_BOTH</constant> and
+ <constant>PDO::FETCH_OBJ</constant>), retrieved in a lazy manner.
+ </para>
+ <para>
+ This can provide memory efficient access (on the PHP side) to unbuffered
+ results on the database server. Whether PDO uses client-side buffering for
+ results depends on the database-specific driver used (and its configuration).
+ </para>
+ <caution>
+ <para>
+ <classname>PDORow</classname> will return <literal>NULL</literal> without
+ any error or warning when accessing properties or keys that are not defined.
+ This can make errors such as typos or queries not returning expected data
+ harder to spot and debug.
+ </para>
+ </caution>
+ <caution>
+ <para>
+ The returned <classname>PDORow</classname> object is updated each time a
+ result is retrieved.
+ </para>
+ </caution>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");
+$result = $stmt->fetch(\PDO::FETCH_LAZY);
+
+print "ID: ". $result[0] ."\n";
+print "Name: {$result->name}\n";
+print "Country: " . $result['country'] ."\n";
+// Returns NULL. No warning or error is raised.
+print "Does not exist: " . var_export($result->does_not_exist, true) . "\n";
+
+$differentResult = $stmt->fetch(\PDO::FETCH_LAZY);
+// The previously retrieved PDORow now points to the newly retrieved result
+print "ID: ". $result[0] ."\n";
+
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+ID: 104
+Name: Chris
+Country: Ukraine
+Does not exist: NULL
+ID: 105
+]]>
+ </screen>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-group" annotations="chunk:false">
+ <title>PDO::FETCH_GROUP (<type>int</type>)</title>
+ <para>
+ <constant>PDO::FETCH_GROUP</constant> returns lists of associative arrays,
+ indexed by a (non-unique) column. This fetch mode only works with
+ <function>PDOStatement::fetchAll</function>.
+ </para>
+ <para>
+ When combined with <constant>PDO::FETCH_UNIQUE</constant>, both modes will
+ use the same column, rendering the combination of these modes useless.
+ </para>
+ <para>
+ This fetch should be combined with one of
+ <constant>PDO::FETCH_ASSOC</constant>, <constant>PDO::FETCH_BOTH</constant>,
+ <constant>PDO::FETCH_NAMED</constant>, <constant>PDO::FETCH_NUM</constant>,
+ <constant>PDO::FETCH_COLUMN</constant> or
+ <constant>PDO::FETCH_FUNC</constant>.
+ </para>
+ <para>
+ If no fetch mode from the above list is given, the current default fetch mode
+ for the <classname>PDOStatement</classname> will be used.
+ </para>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$stmt = $pdo->query("SELECT country, userid, name FROM users");
+$row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
+print_r($row);
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Array
+(
+ [Ukraine] => Array
+ (
+ [0] => Array
+ (
+ [userid] => 104
+ [name] => Chris
+ )
+
+ [1] => Array
+ (
+ [userid] => 108
+ [name] => Sean
+ )
+
+ )
+ [England] => Array
+ (
+ [0] => Array
+ (
+ [userid] => 105
+ [name] => Jamie
+ )
+
+ )
+
+ [Germany] => Array
+ (
+ [0] => Array
+ (
+ [userid] => 107
+ [name] => Robin
+ )
+
+ [1] => Array
+ (
+ [userid] => 109
+ [name] => Toni
+ )
+ )
+)
+]]>
+ </screen>
+ </informalexample>
+ <para>
+ In the above example you'll note that the first column is omitted from the
+ array for each row, only available as the key. It can be included by
+ repeating the column, as in the following example:
+ </para>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$stmt = $pdo->query("SELECT country, userid, name, country FROM users");
+$row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
+print_r($row);
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Array
+(
+ [Ukraine] => Array
+ (
+ [0] => Array
+ (
+ [userid] => 104
+ [name] => Chris
+ [country] => Ukraine
+ )
+
+ [1] => Array
+ (
+ [userid] => 108
+ [name] => Sean
+ [country] => Ukraine
+ )
+
+ )
+ [England] => Array
+ (
+ [0] => Array
+ (
+ [userid] => 105
+ [name] => Jamie
+ [country] => England
+ )
+
+ )
+
+ [Germany] => Array
+ (
+ [0] => Array
+ (
+ [userid] => 107
+ [name] => Robin
+ [country] => Germany
+ )
+
+ [1] => Array
+ (
+ [userid] => 109
+ [name] => Toni
+ [country] => Germany
+ )
+ )
+)
+]]>
+ </screen>
+ </informalexample>
+ </section>
+
+ <section xml:id="pdo.constants.fetch-unique" annotations="chunk:false">
+ <title>PDO::FETCH_UNIQUE (<type>int</type>)</title>
+ <para>
+ <constant>PDO::FETCH_UNIQUE</constant> uses the first column to index records,
+ returning 1 record per index value. This fetch mode only works with
+ <function>PDOStatement::fetchAll</function>.
+ </para>
+ <para>
+ When combined with <constant>PDO::FETCH_GROUP</constant>, both modes will use
+ the same column, rendering the combination of these modes useless.
+ </para>
+ <para>
+ This fetch should be combined with one of
+ <constant>PDO::FETCH_ASSOC</constant>, <constant>PDO::FETCH_BOTH</constant>,
+ <constant>PDO::FETCH_NAMED</constant>, <constant>PDO::FETCH_NUM</constant>,
+ <constant>PDO::FETCH_COLUMN</constant> or
+ <constant>PDO::FETCH_FUNC</constant>.
+ </para>
+ <para>
+ If no fetch mode from the above list is given, the current default fetch mode
+ for the <classname>PDOStatement</classname> will be used.
+ </para>
+ <para>
+ When used with a column that is known to be unique (such as record ID), this
+ mode provides the ability to quickly return results indexed by that value.
+ </para>
+ <note>
+ <para>
+ If the first column is not unique, values will be lost. Which value(s) are
+ lost should be considered undefined.
+ </para>
+ </note>
+ <caution>
+ <para>
+ Filtering records should be done in SQL where possible. The database will
+ use indexes to optimize this process and return only the required records.
+ Selecting more records than required from the database may significantly
+ increase memory usage and query time for larger result sets.
+ </para>
+ </caution>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
+$row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
+print_r($row);
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Array
+(
+ [104] => Array
+ (
+ [name] => Chris
+ [country] => Ukraine
+ )
+
+ [105] => Array
+ (
+ [name] => Jamie
+ [country] => England
+ )
+
+ [107] => Array
+ (
+ [name] => Robin
+ [country] => Germany
+ )
+
+)
+]]>
+ </screen>
+ </informalexample>
+ <para>
+ In the above example you'll note that the first column is omitted from the
+ array for each row, only available as the key. It can be included by
+ repeating the column, as in the following example:
+ </para>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$stmt = $pdo->query("SELECT userid, userid, name, country FROM users LIMIT 3");
+$row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
+print_r($row);
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Array
+(
+ [104] => Array
+ (
+ [userid] => 104
+ [name] => Chris
+ [country] => Ukraine
+ )
+
+ [105] => Array
+ (
+ [userid] => 105
+ [name] => Jamie
+ [country] => England
+ )
+
+ [107] => Array
+ (
+ [userid] => 107
+ [name] => Robin
+ [country] => Germany
+ )
+
+)
+]]>
+ </screen>
+ </informalexample>
+ </section>
+
+</section>
+<!-- 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
+ -->
diff --git a/reference/pdo/constants.xml b/reference/pdo/constants.xml
index af9d1a95d923..1d6165adc9ee 100644
--- a/reference/pdo/constants.xml
+++ b/reference/pdo/constants.xml
@@ -4,951 +4,723 @@
<appendix xml:id="pdo.constants" xmlns="http://docbook.org/ns/docbook">
&reftitle.constants;
&extension.constants;
- <variablelist>
- <varlistentry xml:id="pdo.constants.param-bool">
- <term>
- <constant>PDO::PARAM_BOOL</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Represents a boolean data type.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.param-null">
- <term>
- <constant>PDO::PARAM_NULL</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Represents the SQL NULL data type.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.param-int">
- <term>
- <constant>PDO::PARAM_INT</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Represents the SQL INTEGER data type.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.param-str">
- <term>
- <constant>PDO::PARAM_STR</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Represents the SQL CHAR, VARCHAR, or other string data type.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.param-str-natl">
- <term>
- <constant>PDO::PARAM_STR_NATL</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Flag to denote a string uses the national character set.
- </simpara>
- <simpara>
- Available since PHP 7.2.0
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.param-str-char">
- <term>
- <constant>PDO::PARAM_STR_CHAR</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Flag to denote a string uses the regular character set.
- </simpara>
- <simpara>
- Available since PHP 7.2.0
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.param-lob">
- <term>
- <constant>PDO::PARAM_LOB</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Represents the SQL large object data type.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.param-stmt">
- <term>
- <constant>PDO::PARAM_STMT</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Represents a recordset type. Not currently supported by any drivers.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.param-input-output">
- <term>
- <constant>PDO::PARAM_INPUT_OUTPUT</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Specifies that the parameter is an INOUT parameter for a stored
- procedure. You must bitwise-OR this value with an explicit
- PDO::PARAM_* data type.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-default">
- <term>
- <constant>PDO::FETCH_DEFAULT</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Specifies that the default fetch mode shall be used. Available as of PHP 8.0.7.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-lazy">
- <term>
- <constant>PDO::FETCH_LAZY</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Specifies that the fetch method shall return each row as an object with
- property names that correspond to the column names returned in the result set.
- <constant>PDO::FETCH_LAZY</constant> returns
- a <classname>PDORow</classname> object
- which creates the object property names as they are accessed.
- Not valid inside <methodname>PDOStatement::fetchAll</methodname>.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-assoc">
- <term>
- <constant>PDO::FETCH_ASSOC</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Specifies that the fetch method shall return each row as an array indexed
- by column name as returned in the corresponding result set. If the result
- set contains multiple columns with the same name,
- <constant>PDO::FETCH_ASSOC</constant> returns
- only a single value per column name.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-named">
- <term>
- <constant>PDO::FETCH_NAMED</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Specifies that the fetch method shall return each row as an array indexed
- by column name as returned in the corresponding result set. If the result
- set contains multiple columns with the same name,
- <constant>PDO::FETCH_NAMED</constant> returns
- an array of values per column name.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-num">
- <term>
- <constant>PDO::FETCH_NUM</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Specifies that the fetch method shall return each row as an array indexed
- by column number as returned in the corresponding result set, starting at
- column 0.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-both">
- <term>
- <constant>PDO::FETCH_BOTH</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Specifies that the fetch method shall return each row as an array indexed
- by both column name and number as returned in the corresponding result set,
- starting at column 0.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-obj">
- <term>
- <constant>PDO::FETCH_OBJ</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Specifies that the fetch method shall return each row as an object with
- property names that correspond to the column names returned in the result
- set.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-bound">
- <term>
- <constant>PDO::FETCH_BOUND</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Specifies that the fetch method shall return TRUE and assign the values of
- the columns in the result set to the PHP variables to which they were
- bound with the <methodname>PDOStatement::bindParam</methodname> or
- <methodname>PDOStatement::bindColumn</methodname> methods.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-column">
- <term>
- <constant>PDO::FETCH_COLUMN</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Specifies that the fetch method shall return only a single requested
- column from the next row in the result set.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-class">
- <term>
- <constant>PDO::FETCH_CLASS</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Specifies that the fetch method shall return a new instance of the
- requested class.
- </simpara>
- <note>
- <simpara>
- The object is initialized by mapping the columns from the result set to
- properties in the class. This process occurs before the constructor is
- called, allowing the population of properties 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.
- </simpara>
- </note>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-into">
- <term>
- <constant>PDO::FETCH_INTO</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Specifies that the fetch method shall update an existing instance of the
- requested class, mapping the columns to named properties in the class.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-func">
- <term>
- <constant>PDO::FETCH_FUNC</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Allows completely customize the way data is treated on the fly (only
- valid inside <methodname>PDOStatement::fetchAll</methodname>).
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-group">
- <term>
- <constant>PDO::FETCH_GROUP</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Group return by values. Usually combined with
- <constant>PDO::FETCH_COLUMN</constant> or
- <constant>PDO::FETCH_KEY_PAIR</constant>.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-unique">
- <term>
- <constant>PDO::FETCH_UNIQUE</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Fetch only the unique values.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-key-pair">
- <term>
- <constant>PDO::FETCH_KEY_PAIR</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Fetch a two-column result into an array where the first column is a key and the second column
- is the value.
- </simpara>
- </listitem>
- </varlistentry>
+ &reference.pdo.constants.fetch-modes;
- <varlistentry xml:id="pdo.constants.fetch-classtype">
- <term>
- <constant>PDO::FETCH_CLASSTYPE</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Determine the class name from the value of first column.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-serialize">
- <term>
- <constant>PDO::FETCH_SERIALIZE</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- As <constant>PDO::FETCH_INTO</constant> but object is provided as a serialized string.
- The class constructor is never called if this flag is set.
- Deprecated as of PHP 8.1.0.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-props-late">
- <term>
- <constant>PDO::FETCH_PROPS_LATE</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Call the constructor before setting properties.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-autocommit">
- <term>
- <constant>PDO::ATTR_AUTOCOMMIT</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- If this value is &false;, PDO attempts to disable autocommit so that the
- connection begins a transaction.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-prefetch">
- <term>
- <constant>PDO::ATTR_PREFETCH</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Setting the prefetch size allows you to balance speed against memory
- usage for your application. Not all database/driver combinations support
- setting of the prefetch size. A larger prefetch size results in
- increased performance at the cost of higher memory usage.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-timeout">
- <term>
- <constant>PDO::ATTR_TIMEOUT</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Sets the timeout value in seconds for communications with the database.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-errmode">
- <term>
- <constant>PDO::ATTR_ERRMODE</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- See the <link linkend="pdo.error-handling">Errors and error
- handling</link> section for more information about this attribute.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-server-version">
- <term>
- <constant>PDO::ATTR_SERVER_VERSION</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- This is a read only attribute; it will return information about the
- version of the database server to which PDO is connected.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-client-version">
- <term>
- <constant>PDO::ATTR_CLIENT_VERSION</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- This is a read only attribute; it will return information about the
- version of the client libraries that the PDO driver is using.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-server-info">
- <term>
- <constant>PDO::ATTR_SERVER_INFO</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- This is a read only attribute; it will return some meta information about the
- database server to which PDO is connected.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-connection-status">
- <term>
- <constant>PDO::ATTR_CONNECTION_STATUS</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
+ <section xml:id="pdo.constants.cursors" annotations="chunk:false">
+ <title>Cursors</title>
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-case">
- <term>
- <constant>PDO::ATTR_CASE</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Force column names to a specific case specified by the <literal>PDO::CASE_*</literal>
- constants.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-cursor-name">
- <term>
- <constant>PDO::ATTR_CURSOR_NAME</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Get or set the name to use for a cursor. Most useful when using
- scrollable cursors and positioned updates.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-cursor">
- <term>
- <constant>PDO::ATTR_CURSOR</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Selects the cursor type. PDO currently supports either
- <constant>PDO::CURSOR_FWDONLY</constant> and
- <constant>PDO::CURSOR_SCROLL</constant>. Stick with
- <constant>PDO::CURSOR_FWDONLY</constant> unless you know that you need a
- scrollable cursor.
- </simpara>
- </listitem>
- </varlistentry>
+ <para>
+ See also <constant>PDO::ATTR_CURSOR_NAME</constant>.
+ </para>
- <varlistentry xml:id="pdo.constants.attr-driver-name">
- <term>
- <constant>PDO::ATTR_DRIVER_NAME</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Returns the name of the driver.
- </simpara>
- <para>
- <example><title>using <constant>PDO::ATTR_DRIVER_NAME</constant></title>
- <programlisting role="php">
-<![CDATA[
-<?php
-if ($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') {
- echo "Running on mysql; doing something mysql specific here\n";
-}
-?>
-]]>
- </programlisting>
- </example>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-oracle-nulls">
- <term>
- <constant>PDO::ATTR_ORACLE_NULLS</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Convert empty strings to SQL NULL values on data fetches.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-persistent">
- <term>
- <constant>PDO::ATTR_PERSISTENT</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Request a persistent connection, rather than creating a new connection.
- See <link linkend="pdo.connections">Connections and Connection
- management</link> for more information on this attribute.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-statement-class">
- <term>
- <constant>PDO::ATTR_STATEMENT_CLASS</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Sets the class name of which statements are returned as.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-fetch-catalog-names">
- <term>
- <constant>PDO::ATTR_FETCH_CATALOG_NAMES</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Prepend the containing catalog name to each column name returned in the
- result set. The catalog name and column name are separated by a decimal
- (.) character. Support of this attribute is at the driver level; it may
- not be supported by your driver.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-fetch-table-names">
- <term>
- <constant>PDO::ATTR_FETCH_TABLE_NAMES</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Prepend the containing table name to each column name returned in the
- result set. The table name and column name are separated by a decimal (.)
- character. Support of this attribute is at the driver level; it may not
- be supported by your driver.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-stringify-fetches">
- <term>
- <constant>PDO::ATTR_STRINGIFY_FETCHES</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Forces all fetched values (except &null;) to be treated as strings.
- &null; values remain unchanged unless <constant>PDO::ATTR_ORACLE_NULLS</constant>
- is set to <constant>PDO::NULL_TO_STRING</constant>.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-max-column-len">
- <term>
- <constant>PDO::ATTR_MAX_COLUMN_LEN</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Sets the maximum column name length.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-default-fetch-mode">
- <term>
- <constant>PDO::ATTR_DEFAULT_FETCH_MODE</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
+ <variablelist>
+ <varlistentry xml:id="pdo.constants.fetch-ori-next">
+ <term>
+ <constant>PDO::FETCH_ORI_NEXT</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Fetch the next row in the result set. Valid only for scrollable cursors.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.fetch-ori-prior">
+ <term>
+ <constant>PDO::FETCH_ORI_PRIOR</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Fetch the previous row in the result set. Valid only for scrollable
+ cursors.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.fetch-ori-first">
+ <term>
+ <constant>PDO::FETCH_ORI_FIRST</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Fetch the first row in the result set. Valid only for scrollable cursors.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.fetch-ori-last">
+ <term>
+ <constant>PDO::FETCH_ORI_LAST</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Fetch the last row in the result set. Valid only for scrollable cursors.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.fetch-ori-abs">
+ <term>
+ <constant>PDO::FETCH_ORI_ABS</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Fetch the requested row by row number from the result set. Valid only
+ for scrollable cursors.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.fetch-ori-rel">
+ <term>
+ <constant>PDO::FETCH_ORI_REL</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Fetch the requested row by relative position from the current position
+ of the cursor in the result set. Valid only for scrollable cursors.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.cursor-fwdonly">
+ <term>
+ <constant>PDO::CURSOR_FWDONLY</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Create a <classname>PDOStatement</classname> object with a forward-only cursor. This is the
+ default cursor choice, as it is the fastest and most common data access
+ pattern in PHP.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.cursor-scroll">
+ <term>
+ <constant>PDO::CURSOR_SCROLL</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Create a <classname>PDOStatement</classname> object with a scrollable cursor. Pass the
+ <literal>PDO::FETCH_ORI_*</literal> constants to control the rows fetched from the result set.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-emulate-prepares">
- <term>
- <constant>PDO::ATTR_EMULATE_PREPARES</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
+ <section annotations="chunk:false">
+ <title>Other Constants</title>
+ <variablelist>
+ <varlistentry xml:id="pdo.constants.param-bool">
+ <term>
+ <constant>PDO::PARAM_BOOL</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Represents a boolean data type.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.param-null">
+ <term>
+ <constant>PDO::PARAM_NULL</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Represents the SQL NULL data type.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.param-int">
+ <term>
+ <constant>PDO::PARAM_INT</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Represents the SQL INTEGER data type.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.param-str">
+ <term>
+ <constant>PDO::PARAM_STR</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Represents the SQL CHAR, VARCHAR, or other string data type.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.param-str-natl">
+ <term>
+ <constant>PDO::PARAM_STR_NATL</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Flag to denote a string uses the national character set.
+ </simpara>
+ <simpara>
+ Available since PHP 7.2.0
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.param-str-char">
+ <term>
+ <constant>PDO::PARAM_STR_CHAR</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Flag to denote a string uses the regular character set.
+ </simpara>
+ <simpara>
+ Available since PHP 7.2.0
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.param-lob">
+ <term>
+ <constant>PDO::PARAM_LOB</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Represents the SQL large object data type.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.param-stmt">
+ <term>
+ <constant>PDO::PARAM_STMT</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Represents a recordset type. Not currently supported by any drivers.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.param-input-output">
+ <term>
+ <constant>PDO::PARAM_INPUT_OUTPUT</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Specifies that the parameter is an INOUT parameter for a stored
+ procedure. You must bitwise-OR this value with an explicit
+ PDO::PARAM_* data type.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-autocommit">
+ <term>
+ <constant>PDO::ATTR_AUTOCOMMIT</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ If this value is &false;, PDO attempts to disable autocommit so that the
+ connection begins a transaction.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-prefetch">
+ <term>
+ <constant>PDO::ATTR_PREFETCH</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Setting the prefetch size allows you to balance speed against memory
+ usage for your application. Not all database/driver combinations support
+ setting of the prefetch size. A larger prefetch size results in
+ increased performance at the cost of higher memory usage.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-timeout">
+ <term>
+ <constant>PDO::ATTR_TIMEOUT</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Sets the timeout value in seconds for communications with the database.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-errmode">
+ <term>
+ <constant>PDO::ATTR_ERRMODE</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ See the <link linkend="pdo.error-handling">Errors and error
+ handling</link> section for more information about this attribute.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-server-version">
+ <term>
+ <constant>PDO::ATTR_SERVER_VERSION</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ This is a read only attribute; it will return information about the
+ version of the database server to which PDO is connected.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-client-version">
+ <term>
+ <constant>PDO::ATTR_CLIENT_VERSION</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ This is a read only attribute; it will return information about the
+ version of the client libraries that the PDO driver is using.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-server-info">
+ <term>
+ <constant>PDO::ATTR_SERVER_INFO</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ This is a read only attribute; it will return some meta information about the
+ database server to which PDO is connected.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-connection-status">
+ <term>
+ <constant>PDO::ATTR_CONNECTION_STATUS</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.attr-default-str-param">
- <term>
- <constant>PDO::ATTR_DEFAULT_STR_PARAM</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Sets the default string parameter type, this can be one of <constant>PDO::PARAM_STR_NATL</constant>
- and <constant>PDO::PARAM_STR_CHAR</constant>.
- </simpara>
- <simpara>
- Available since PHP 7.2.0.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.errmode-silent">
- <term>
- <constant>PDO::ERRMODE_SILENT</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Do not raise an error or exception if an error occurs. The developer is
- expected to explicitly check for errors. This is the default mode.
- See <link linkend="pdo.error-handling">Errors and error handling</link>
- for more information about this attribute.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.errmode-warning">
- <term>
- <constant>PDO::ERRMODE_WARNING</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Issue a PHP <constant>E_WARNING</constant> message if an error occurs.
- See <link linkend="pdo.error-handling">Errors and error handling</link>
- for more information about this attribute.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.errmode-exception">
- <term>
- <constant>PDO::ERRMODE_EXCEPTION</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Throw a <classname>PDOException</classname> if an error occurs.
- See <link linkend="pdo.error-handling">Errors and error handling</link>
- for more information about this attribute.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.case-natural">
- <term>
- <constant>PDO::CASE_NATURAL</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Leave column names as returned by the database driver.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.case-lower">
- <term>
- <constant>PDO::CASE_LOWER</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Force column names to lower case.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.case-upper">
- <term>
- <constant>PDO::CASE_UPPER</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Force column names to upper case.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.null-natural">
- <term>
- <constant>PDO::NULL_NATURAL</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-case">
+ <term>
+ <constant>PDO::ATTR_CASE</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Force column names to a specific case specified by the <literal>PDO::CASE_*</literal>
+ constants.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-cursor-name">
+ <term>
+ <constant>PDO::ATTR_CURSOR_NAME</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Get or set the name to use for a cursor. Most useful when using
+ scrollable cursors and positioned updates.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-cursor">
+ <term>
+ <constant>PDO::ATTR_CURSOR</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Selects the cursor type. PDO currently supports either
+ <constant>PDO::CURSOR_FWDONLY</constant> and
+ <constant>PDO::CURSOR_SCROLL</constant>. Stick with
+ <constant>PDO::CURSOR_FWDONLY</constant> unless you know that you need a
+ scrollable cursor.
+ </simpara>
+ </listitem>
+ </varlistentry>
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.null-empty-string">
- <term>
- <constant>PDO::NULL_EMPTY_STRING</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
+ <varlistentry xml:id="pdo.constants.attr-driver-name">
+ <term>
+ <constant>PDO::ATTR_DRIVER_NAME</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Returns the name of the driver.
+ </simpara>
+ <para>
+ <example><title>using <constant>PDO::ATTR_DRIVER_NAME</constant></title>
+ <programlisting role="php">
+ <![CDATA[
+ <?php
+ if ($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') {
+ echo "Running on mysql; doing something mysql specific here\n";
+ }
+ ?>
+ ]]>
+ </programlisting>
+ </example>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-oracle-nulls">
+ <term>
+ <constant>PDO::ATTR_ORACLE_NULLS</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Convert empty strings to SQL NULL values on data fetches.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-persistent">
+ <term>
+ <constant>PDO::ATTR_PERSISTENT</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Request a persistent connection, rather than creating a new connection.
+ See <link linkend="pdo.connections">Connections and Connection
+ management</link> for more information on this attribute.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-statement-class">
+ <term>
+ <constant>PDO::ATTR_STATEMENT_CLASS</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Sets the class name of which statements are returned as.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-fetch-catalog-names">
+ <term>
+ <constant>PDO::ATTR_FETCH_CATALOG_NAMES</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Prepend the containing catalog name to each column name returned in the
+ result set. The catalog name and column name are separated by a decimal
+ (.) character. Support of this attribute is at the driver level; it may
+ not be supported by your driver.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-fetch-table-names">
+ <term>
+ <constant>PDO::ATTR_FETCH_TABLE_NAMES</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Prepend the containing table name to each column name returned in the
+ result set. The table name and column name are separated by a decimal (.)
+ character. Support of this attribute is at the driver level; it may not
+ be supported by your driver.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-stringify-fetches">
+ <term>
+ <constant>PDO::ATTR_STRINGIFY_FETCHES</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Forces all fetched values (except &null;) to be treated as strings.
+ &null; values remain unchanged unless <constant>PDO::ATTR_ORACLE_NULLS</constant>
+ is set to <constant>PDO::NULL_TO_STRING</constant>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-max-column-len">
+ <term>
+ <constant>PDO::ATTR_MAX_COLUMN_LEN</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Sets the maximum column name length.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-default-fetch-mode">
+ <term>
+ <constant>PDO::ATTR_DEFAULT_FETCH_MODE</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.null-to-string">
- <term>
- <constant>PDO::NULL_TO_STRING</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-emulate-prepares">
+ <term>
+ <constant>PDO::ATTR_EMULATE_PREPARES</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-ori-next">
- <term>
- <constant>PDO::FETCH_ORI_NEXT</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Fetch the next row in the result set. Valid only for scrollable cursors.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-ori-prior">
- <term>
- <constant>PDO::FETCH_ORI_PRIOR</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Fetch the previous row in the result set. Valid only for scrollable
- cursors.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-ori-first">
- <term>
- <constant>PDO::FETCH_ORI_FIRST</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Fetch the first row in the result set. Valid only for scrollable cursors.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-ori-last">
- <term>
- <constant>PDO::FETCH_ORI_LAST</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Fetch the last row in the result set. Valid only for scrollable cursors.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-ori-abs">
- <term>
- <constant>PDO::FETCH_ORI_ABS</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Fetch the requested row by row number from the result set. Valid only
- for scrollable cursors.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.fetch-ori-rel">
- <term>
- <constant>PDO::FETCH_ORI_REL</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Fetch the requested row by relative position from the current position
- of the cursor in the result set. Valid only for scrollable cursors.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.cursor-fwdonly">
- <term>
- <constant>PDO::CURSOR_FWDONLY</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Create a <classname>PDOStatement</classname> object with a forward-only cursor. This is the
- default cursor choice, as it is the fastest and most common data access
- pattern in PHP.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.cursor-scroll">
- <term>
- <constant>PDO::CURSOR_SCROLL</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Create a <classname>PDOStatement</classname> object with a scrollable cursor. Pass the
- <literal>PDO::FETCH_ORI_*</literal> constants to control the rows fetched from the result set.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.err-none">
- <term>
- <constant>PDO::ERR_NONE</constant>
- (<type>string</type>)
- </term>
- <listitem>
- <simpara>
- Corresponds to SQLSTATE '00000', meaning that the SQL statement was
- successfully issued with no errors or warnings. This constant is for
- your convenience when checking <methodname>PDO::errorCode</methodname> or
- <methodname>PDOStatement::errorCode</methodname> to determine if an error
- occurred. You will usually know if this is the case by examining the
- return code from the method that raised the error condition anyway.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.param-evt-alloc">
- <term>
- <constant>PDO::PARAM_EVT_ALLOC</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Allocation event
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.param-evt-free">
- <term>
- <constant>PDO::PARAM_EVT_FREE</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Deallocation event
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.param-evt-exec-pre">
- <term>
- <constant>PDO::PARAM_EVT_EXEC_PRE</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Event triggered prior to execution of a prepared statement.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.param-evt-exec-post">
- <term>
- <constant>PDO::PARAM_EVT_EXEC_POST</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Event triggered subsequent to execution of a prepared statement.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.param-evt-fetch-pre">
- <term>
- <constant>PDO::PARAM_EVT_FETCH_PRE</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Event triggered prior to fetching a result from a resultset.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.param-evt-fetch-post">
- <term>
- <constant>PDO::PARAM_EVT_FETCH_POST</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Event triggered subsequent to fetching a result from a resultset.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.param-evt-normalize">
- <term>
- <constant>PDO::PARAM_EVT_NORMALIZE</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Event triggered during bound parameter registration
- allowing the driver to normalize the parameter name.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry xml:id="pdo.constants.sqlite-deterministic">
- <term>
- <constant>PDO::SQLITE_DETERMINISTIC</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Specifies that a function created with <methodname>PDO::sqliteCreateFunction</methodname>
- is deterministic, i.e. it always returns the same result given the same inputs within
- a single SQL statement. (Available as of PHP 7.1.4.)
- </simpara>
- </listitem>
- </varlistentry>
- </variablelist>
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.attr-default-str-param">
+ <term>
+ <constant>PDO::ATTR_DEFAULT_STR_PARAM</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Sets the default string parameter type, this can be one of <constant>PDO::PARAM_STR_NATL</constant>
+ and <constant>PDO::PARAM_STR_CHAR</constant>.
+ </simpara>
+ <simpara>
+ Available since PHP 7.2.0.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.errmode-silent">
+ <term>
+ <constant>PDO::ERRMODE_SILENT</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Do not raise an error or exception if an error occurs. The developer is
+ expected to explicitly check for errors. This is the default mode.
+ See <link linkend="pdo.error-handling">Errors and error handling</link>
+ for more information about this attribute.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.errmode-warning">
+ <term>
+ <constant>PDO::ERRMODE_WARNING</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Issue a PHP <constant>E_WARNING</constant> message if an error occurs.
+ See <link linkend="pdo.error-handling">Errors and error handling</link>
+ for more information about this attribute.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.errmode-exception">
+ <term>
+ <constant>PDO::ERRMODE_EXCEPTION</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Throw a <classname>PDOException</classname> if an error occurs.
+ See <link linkend="pdo.error-handling">Errors and error handling</link>
+ for more information about this attribute.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.case-natural">
+ <term>
+ <constant>PDO::CASE_NATURAL</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Leave column names as returned by the database driver.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.case-lower">
+ <term>
+ <constant>PDO::CASE_LOWER</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Force column names to lower case.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.case-upper">
+ <term>
+ <constant>PDO::CASE_UPPER</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Force column names to upper case.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.null-natural">
+ <term>
+ <constant>PDO::NULL_NATURAL</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.null-empty-string">
+ <term>
+ <constant>PDO::NULL_EMPTY_STRING</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.null-to-string">
+ <term>
+ <constant>PDO::NULL_TO_STRING</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.err-none">
+ <term>
+ <constant>PDO::ERR_NONE</constant>
+ (<type>string</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Corresponds to SQLSTATE '00000', meaning that the SQL statement was
+ successfully issued with no errors or warnings. This constant is for
+ your convenience when checking <methodname>PDO::errorCode</methodname> or
+ <methodname>PDOStatement::errorCode</methodname> to determine if an error
+ occurred. You will usually know if this is the case by examining the
+ return code from the method that raised the error condition anyway.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.param-evt-alloc">
+ <term>
+ <constant>PDO::PARAM_EVT_ALLOC</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Allocation event
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.param-evt-free">
+ <term>
+ <constant>PDO::PARAM_EVT_FREE</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Deallocation event
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.param-evt-exec-pre">
+ <term>
+ <constant>PDO::PARAM_EVT_EXEC_PRE</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Event triggered prior to execution of a prepared statement.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.param-evt-exec-post">
+ <term>
+ <constant>PDO::PARAM_EVT_EXEC_POST</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Event triggered subsequent to execution of a prepared statement.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.param-evt-fetch-pre">
+ <term>
+ <constant>PDO::PARAM_EVT_FETCH_PRE</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Event triggered prior to fetching a result from a resultset.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.param-evt-fetch-post">
+ <term>
+ <constant>PDO::PARAM_EVT_FETCH_POST</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Event triggered subsequent to fetching a result from a resultset.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.param-evt-normalize">
+ <term>
+ <constant>PDO::PARAM_EVT_NORMALIZE</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Event triggered during bound parameter registration
+ allowing the driver to normalize the parameter name.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="pdo.constants.sqlite-deterministic">
+ <term>
+ <constant>PDO::SQLITE_DETERMINISTIC</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Specifies that a function created with <methodname>PDO::sqliteCreateFunction</methodname>
+ is deterministic, i.e. it always returns the same result given the same inputs within
+ a single SQL statement. (Available as of PHP 7.1.4.)
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
</appendix>
<!-- Keep this comment at the end of the file
Local variables:
diff --git a/reference/pdo/pdorow.xml b/reference/pdo/pdorow.xml
index 270d850f5f1a..8352c248b8c0 100644
--- a/reference/pdo/pdorow.xml
+++ b/reference/pdo/pdorow.xml
@@ -11,7 +11,7 @@
<para>
Represents a row from a result set returned
by <methodname>PDOStatement::fetch</methodname>
- called with <constant>PDO_FETCH_LAZY</constant> fetch mode.
+ called with <constant>PDO::FETCH_LAZY</constant> fetch mode.
</para>
<para>
Objects of this class cannot be instantiated and are not serializable.