diff --git a/reference/pdo/constants.fetch-modes.xml b/reference/pdo/constants.fetch-modes.xml new file mode 100644 index 000000000000..32df6adf4c9a --- /dev/null +++ b/reference/pdo/constants.fetch-modes.xml @@ -0,0 +1,1452 @@ + +
+ Fetch Modes + + + See cursor constants for the + PDO::FETCH_ORI_* cursor constants. + + +
+ Basic Fetch Modes + + + + + Fetch Mode + Summary + + + + + + PDO::FETCH_DEFAULT + + + Special value for using the current default fetch mode. + + + + + PDO::FETCH_ASSOC + + + Array indexed by column name only. + + + + + PDO::FETCH_BOTH (Default) + + + Array indexed by both column number and name. + + + + + PDO::FETCH_NAMED + + + Variant of PDO::FETCH_ASSOC that retains duplicated + columns. + + + + + PDO::FETCH_NUM + + + Array indexed by column number only. + + + + + PDO::FETCH_COLUMN + + + A single value / column. + + + + + PDO::FETCH_KEY_PAIR + + + Key-Value pairs, indexed by the first column. + + + + + PDO::FETCH_FUNC + + + Use a function to create the return value. + (PDOStatement::fetchAll only) + + + + + PDO::FETCH_OBJ + + + Anonymous (stdClass) object. + + + + + PDO::FETCH_CLASS + + + An object of a specified class. + + + + + +
+ +
+ <constant>PDO::FETCH_CLASS</constant> options + + + These modes are used to implement options when using + PDO::FETCH_CLASS. + + + + + + + Fetch Mode + Summary + + + + + + PDO::FETCH_CLASSTYPE + + + Use the first column as the class name. + + + + + PDO::FETCH_PROPS_LATE + + + Call the constructor before setting properties. + + + + + PDO::FETCH_SERIALIZE + + + Use PHP serialized data. Deprecated as of PHP 8.1.0. + + + + + +
+ +
+ Single Result Modes + + + The following modes can not be used with + PDOStatement::fetchAll. + + + + + + + Fetch Mode + Summary + + + + + + PDO::FETCH_BOUND + + + Bind values to specified variables. + + + + + PDO::FETCH_INTO + + + Update an existing object. + + + + + PDO::FETCH_LAZY + + + Lazy fetch via PDORow for array- and object-like + access. + + + + + +
+ +
+ + Special Behavior Flags for <function>PDOStatement::fetchAll</function> + + + + The following special modes for multiple results only work with + PDOStatement::fetchAll and do not work with some other + fetch modes. Check the full documentation for details. + + + + + + + Fetch Mode + Summary + + + + + + PDO::FETCH_GROUP + + + Results are grouped by the first column. + + + + + PDO::FETCH_UNIQUE + + + Results are (uniquely) indexed by the first column. + + + + + +
+ +
+ Handling of Duplicated Column Names + + 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. + + + 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. + + + Which value is returned for a given duplicated name should be considered + undefined. + + + To avoid this issue, explicitly name columns using an alias. For example: + + + + + + + + See also PDO::FETCH_NAMED, + PDO::ATTR_FETCH_TABLE_NAMES and + PDO::ATTR_FETCH_CATALOG_NAMES. + +
+ +
+ Setting the Default Fetch Mode + + You can set the default fetch mode for all queries using + PDO::ATTR_DEFAULT_FETCH_MODE with + PDO::__construct or + PDO::setAttribute. + + + You can set the default fetch mode for a specific statement using + PDOStatement::setFetchMode. This affects reuse as a + prepared statement and iteration (using + foreach). + + + + PDOStatement::setAttribute cannot be used to set the + default fetch mode. It only accepts driver specific attributes and silently + ignores attributes that are not recognized. + + +
+ +
+ PDO::FETCH_DEFAULT (<type>int</type>) + + Available since PHP 8.0.7. + + + This is a special value that uses the current default fetch mode for a + PDOStatement. It's specifically useful as the default + value for method parameters when extending + PDOStatement for use with + PDO::ATTR_STATEMENT_CLASS. + + + This value cannot be used with + PDO::ATTR_DEFAULT_FETCH_MODE. + +
+ +
+ PDO::FETCH_ASSOC (<type>int</type>) + + PDO::FETCH_ASSOC returns an array indexed by column name + only. + + + +query("SELECT userid, name, country FROM users"); +$row = $stmt->fetch(\PDO::FETCH_ASSOC); +print_r($row); +]]> + + &example.outputs; + + 104 + [name] => Chris + [country] => Ukraine +) +]]> + + +
+ +
+ PDO::FETCH_BOTH (<type>int</type>) + + This is the default fetch mode. + + + PDO::FETCH_BOTH returns an array indexed by both column + number and name. This means that every returned value is duplicated for each + result row. + + + 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. + + + + 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 + SELECT *. + + + + + 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. + + + + +query("SELECT userid, name, country FROM users"); +$row = $stmt->fetch(\PDO::FETCH_BOTH); +print_r($row); +]]> + + &example.outputs; + + 104, + [0] => 104, + [name] => Chris, + [1] => Chris, + [country] => Ukraine, + [2] => Ukraine +) +]]> + + +
+ +
+ PDO::FETCH_NAMED (<type>int</type>) + + PDO::FETCH_NAMED returns results in the same format as + PDO::FETCH_ASSOC except that where multiple columns use + the same name, all values are returned as a list. + + + For more information on handling of duplicated column names and alternatives, + see the handling of + duplicated names section above. + + + The order in which duplicated values are returned should be considered + undefined. There's no way to tell where each value came from. + + + +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); +]]> + + &example.outputs; + + 109 + [name] => Array + ( + [0] => Toni + [1] => Chris + ) + [country] => Germany + [referred_by] = 104 +) +]]> + + +
+ +
+ PDO::FETCH_NUM (<type>int</type>) + + PDO::FETCH_NUM 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. + + + + 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 + SELECT *. + + + + +query("SELECT userid, name, country FROM users"); +$row = $stmt->fetch(\PDO::FETCH_NUM); +print_r($row); +]]> + + &example.outputs; + + 104 + [1] => Chris + [2] => Ukraine +) +]]> + + +
+ +
+ PDO::FETCH_COLUMN (<type>int</type>) + + PDO::FETCH_COLUMN returns values from a single column. + Use the second argument for PDOStatement::setFetchMode + or PDOStatement::fetchAll to specify which column is + returned. + + + If the specified column does not exist a ValueError + will be thrown. + + + +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); +]]> + + &example.outputs; + + Chris + [1] => Jamie + [2] => Robin +) + +Array +( + [0] => Ukraine + [1] => England + [2] => Germany +) +]]> + + +
+ +
+ PDO::FETCH_KEY_PAIR (<type>int</type>) + + PDO::FETCH_KEY_PAIR returns pairs of values, indexed by + the first column. The results must contain only 2 columns. This fetch mode + only makes sense with PDOStatement::fetchAll. + + + + If the first column is not unique, values will be lost. Which value(s) are + lost / retained should be considered undefined. + + + + +query("SELECT name, country FROM users LIMIT 3"); +$row = $stmt->fetchAll(\PDO::FETCH_KEY_PAIR); +print_r($row); +]]> + + &example.outputs; + + Ukraine + [Jamie] => England + [Robin] => Germany +) +]]> + + +
+ +
+ PDO::FETCH_FUNC (<type>int</type>) + + Specify a function to create the returned value. This mode can only be used + with PDOStatement::fetchAll. + + + The function received the values as parameters. There's no way to retrieve + the column a given value was associated with. You must make sure the column + order in the query matches that expected by the function. + + + + The effects of PDO::FETCH_GROUP and + PDO::FETCH_UNIQUE are applied to results before the + function is called. + + + + + $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); +]]> + + &example.outputs; + + 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 + ) + +) +]]> + + +
+ +
+ PDO::FETCH_OBJ (<type>int</type>) + + PDO::FETCH_OBJ returns a stdClass + object. + + + See also PDOStatement::fetchObject and + PDO::FETCH_CLASS. + + + +query("SELECT userid, name, country FROM users"); +$row = $stmt->fetch(\PDO::FETCH_OBJ); +print_r($row); +]]> + + &example.outputs; + + 104 + [name] => Chris + [country] => Ukraine +) +]]> + + +
+ +
+ PDO::FETCH_CLASS (<type>int</type>) + + Returns an object of a specified class. For additional behaviors see the + option flags. + + + 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. + + + See also PDOStatement::fetchObject. + + + +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); +]]> + + &example.outputs.similar; + + + int(104) + ["name"]=> + string(5) "Chris" + ["country"]=> + string(7) "Ukraine" + ["referred_by_userid"]=> + NULL +} +]]> + + +
+ +
+ PDO::FETCH_CLASSTYPE (<type>int</type>) + + This fetch mode can only be used combined with + PDO::FETCH_CLASS (and + its other options). + + + When this fetch mode is used, PDO will use the first returned column as the + name of the class to return. + + + If the specified class cannot be found, a stdClass + object will be returned, without warning or error. + + + +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); +]]> + + &example.outputs.similar; + + + int(104) + ["name"]=> + string(5) "Chris" + ["country"]=> + string(7) "Ukraine" + ["referred_by_userid"]=> + NULL +} +]]> + + +
+ +
+ PDO::FETCH_PROPS_LATE (<type>int</type>) + + This fetch mode can only be used combined with + PDO::FETCH_CLASS (and + its other options). + + + When this fetch mode is used, the constructor will be called before the + properties are set. + + + +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); +]]> + + &example.outputs.similar; + + + int(104) + ["name"]=> + string(5) "Chris" + ["country"]=> + string(7) "Ukraine" + ["referred_by_userid"]=> + NULL +} +]]> + + +
+ +
+ PDO::FETCH_SERIALIZE (<type>int</type>) + + + This feature has been DEPRECATED as of PHP 8.1.0. + Relying on this feature is highly discouraged. + + + + This fetch mode can only be used combined with + PDO::FETCH_CLASS (and + its other options). + + + When this fetch mode is used, the specified class must be + Serializable. + + + + This feature does not support a string that contains a complete serialized + object (with serialize). + + + + + This fetch mode does not call the constructor. + + + + +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); +]]> + + &example.outputs.similar; + + + int(200) + ["name"]=> + string(4) "Seri" + ["country"]=> + string(5) "Syria" + ["referred_by_userid"]=> + NULL +} +]]> + + +
+ +
+ PDO::FETCH_BOUND (<type>int</type>) + + This fetch mode can not be used with + PDOStatement::fetchAll. + + + This fetch mode does not directly return a result, but binds values to + variables specified with PDOStatement::bindParam or + PDOStatement::bindColumn. The called fetch method + returns TRUE. + + + + When using prepared statements, to work correctly, variables must be bound + after the query is executed. + + + +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"; +} +]]> + + &example.outputs; + + + +
+ +
+ PDO::FETCH_INTO (<type>int</type>) + + This fetch mode can not be used with + PDOStatement::fetchAll. + + + This fetch mode updates properties in the specified object. The object is + returned on success. + + + 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. + + + Properties must be public and can not be + readonly. + + + + There's no way to change the object to be updated without using + PDOStatement::setFetchMode between retrieving each + record. + + + + +setFetchMode(\PDO::FETCH_INTO, $obj); + +$stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users"); +$result = $stmt->fetch(); +var_dump($result); +]]> + + &example.outputs.similar; + + + int(104) + ["name"]=> + string(5) "Chris" + ["country"]=> + string(7) "Ukraine" + ["referred_by_userid"]=> + NULL +} +]]> + + +
+ +
+ PDO::FETCH_LAZY (<type>int</type>) + + This fetch mode can not be used with + PDOStatement::fetchAll. + + + This fetch mode returns a PDORow object which provides + both array- and object-like access to values (i.e. combines the behavior of + PDO::FETCH_BOTH and + PDO::FETCH_OBJ), retrieved in a lazy manner. + + + 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). + + + + PDORow will return NULL 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. + + + + + The returned PDORow object is updated each time a + result is retrieved. + + + +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"; +print "Does not exist: " . ($result->does_not_exist ?? "NULL") . "\n"; + +$differentResult = $stmt->fetch(\PDO::FETCH_LAZY); +// The previously retrieved PDORow now points to the newly retrieved result +print "ID: ". $result[0] ."\n"; + +]]> + + &example.outputs; + + + +
+ +
+ PDO::FETCH_GROUP (<type>int</type>) + + PDO::FETCH_GROUP returns lists of associative arrays, + indexed by a (non-unique) column. This fetch mode only works with + PDOStatement::fetchAll. + + + When combined with PDO::FETCH_UNIQUE, both modes will + use the same column, rendering the combination of these modes useless. + + + This fetch should be combined with one of + PDO::FETCH_ASSOC, PDO::FETCH_BOTH, + PDO::FETCH_NAMED, PDO::FETCH_NUM, + PDO::FETCH_COLUMN or + PDO::FETCH_FUNC. + + + +query("SELECT country, userid, name FROM users"); +$row = $stmt->fetchAll(\PDO::FETCH_GROUP); +print_r($row); +]]> + + &example.outputs; + + 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 + ) + ) +) +]]> + + + + 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: + + + +query("SELECT country, userid, name, country FROM users"); +$row = $stmt->fetchAll(\PDO::FETCH_GROUP); +print_r($row); +]]> + + &example.outputs; + + 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 + ) + ) +) +]]> + + +
+ +
+ PDO::FETCH_UNIQUE (<type>int</type>) + + PDO::FETCH_UNIQUE uses the first column to index records, + returning 1 record per index value. This fetch mode only works with + PDOStatement::fetchAll. + + + When combined with PDO::FETCH_GROUP, both modes will use + the same column, rendering the combination of these modes useless. + + + This fetch should be combined with one of + PDO::FETCH_ASSOC, PDO::FETCH_BOTH, + PDO::FETCH_NAMED, PDO::FETCH_NUM, + PDO::FETCH_COLUMN or + PDO::FETCH_FUNC. + + + If no fetch mode from the above list is given, the current default fetch mode + for the PDOStatement will be used. + + + 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. + + + + If the first column is not unique, values will be lost. Which value(s) are + lost / retained should be considered undefined. + + + + + 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. + + + + +query("SELECT userid, name, country FROM users LIMIT 3"); +$row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC); +print_r($row); +]]> + + &example.outputs; + + Array + ( + [name] => Chris + [country] => Ukraine + ) + + [105] => Array + ( + [name] => Jamie + [country] => England + ) + + [107] => Array + ( + [name] => Robin + [country] => Germany + ) + +) +]]> + + + + 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: + + + +query("SELECT userid, userid, name, country FROM users LIMIT 3"); +$row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC); +print_r($row); +]]> + + &example.outputs; + + Array + ( + [userid] => 104 + [name] => Chris + [country] => Ukraine + ) + + [105] => Array + ( + [userid] => 105 + [name] => Jamie + [country] => England + ) + + [107] => Array + ( + [userid] => 107 + [name] => Robin + [country] => Germany + ) + +) +]]> + + +
+ +
+ 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 @@ &reftitle.constants; &extension.constants; - - - - PDO::PARAM_BOOL - (int) - - - - Represents a boolean data type. - - - - - - PDO::PARAM_NULL - (int) - - - - Represents the SQL NULL data type. - - - - - - PDO::PARAM_INT - (int) - - - - Represents the SQL INTEGER data type. - - - - - - PDO::PARAM_STR - (int) - - - - Represents the SQL CHAR, VARCHAR, or other string data type. - - - - - - PDO::PARAM_STR_NATL - (int) - - - - Flag to denote a string uses the national character set. - - - Available since PHP 7.2.0 - - - - - - PDO::PARAM_STR_CHAR - (int) - - - - Flag to denote a string uses the regular character set. - - - Available since PHP 7.2.0 - - - - - - PDO::PARAM_LOB - (int) - - - - Represents the SQL large object data type. - - - - - - PDO::PARAM_STMT - (int) - - - - Represents a recordset type. Not currently supported by any drivers. - - - - - - PDO::PARAM_INPUT_OUTPUT - (int) - - - - 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. - - - - - - PDO::FETCH_DEFAULT - (int) - - - - Specifies that the default fetch mode shall be used. Available as of PHP 8.0.7. - - - - - - PDO::FETCH_LAZY - (int) - - - - 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. - PDO::FETCH_LAZY returns - a PDORow object - which creates the object property names as they are accessed. - Not valid inside PDOStatement::fetchAll. - - - - - - PDO::FETCH_ASSOC - (int) - - - - 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, - PDO::FETCH_ASSOC returns - only a single value per column name. - - - - - - PDO::FETCH_NAMED - (int) - - - - 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, - PDO::FETCH_NAMED returns - an array of values per column name. - - - - - - PDO::FETCH_NUM - (int) - - - - 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. - - - - - - PDO::FETCH_BOTH - (int) - - - - 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. - - - - - - PDO::FETCH_OBJ - (int) - - - - 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. - - - - - - PDO::FETCH_BOUND - (int) - - - - 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 PDOStatement::bindParam or - PDOStatement::bindColumn methods. - - - - - - PDO::FETCH_COLUMN - (int) - - - - Specifies that the fetch method shall return only a single requested - column from the next row in the result set. - - - - - - PDO::FETCH_CLASS - (int) - - - - Specifies that the fetch method shall return a new instance of the - requested class. - - - - 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 readonly. If - a property does not exist in the class, the magic - __set() - method will be invoked if it exists; otherwise, a dynamic public property - will be created. However, when PDO::FETCH_PROPS_LATE - is also given, the constructor is called before the - properties are populated. - - - - - - - PDO::FETCH_INTO - (int) - - - - Specifies that the fetch method shall update an existing instance of the - requested class, mapping the columns to named properties in the class. - - - - - - PDO::FETCH_FUNC - (int) - - - - Allows completely customize the way data is treated on the fly (only - valid inside PDOStatement::fetchAll). - - - - - - PDO::FETCH_GROUP - (int) - - - - Group return by values. Usually combined with - PDO::FETCH_COLUMN or - PDO::FETCH_KEY_PAIR. - - - - - - PDO::FETCH_UNIQUE - (int) - - - - Fetch only the unique values. - - - - - - PDO::FETCH_KEY_PAIR - (int) - - - - Fetch a two-column result into an array where the first column is a key and the second column - is the value. - - - + &reference.pdo.constants.fetch-modes; - - - PDO::FETCH_CLASSTYPE - (int) - - - - Determine the class name from the value of first column. - - - - - - PDO::FETCH_SERIALIZE - (int) - - - - As PDO::FETCH_INTO 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. - - - - - - PDO::FETCH_PROPS_LATE - (int) - - - - Call the constructor before setting properties. - - - - - - PDO::ATTR_AUTOCOMMIT - (int) - - - - If this value is &false;, PDO attempts to disable autocommit so that the - connection begins a transaction. - - - - - - PDO::ATTR_PREFETCH - (int) - - - - 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. - - - - - - PDO::ATTR_TIMEOUT - (int) - - - - Sets the timeout value in seconds for communications with the database. - - - - - - PDO::ATTR_ERRMODE - (int) - - - - See the Errors and error - handling section for more information about this attribute. - - - - - - PDO::ATTR_SERVER_VERSION - (int) - - - - This is a read only attribute; it will return information about the - version of the database server to which PDO is connected. - - - - - - PDO::ATTR_CLIENT_VERSION - (int) - - - - This is a read only attribute; it will return information about the - version of the client libraries that the PDO driver is using. - - - - - - PDO::ATTR_SERVER_INFO - (int) - - - - This is a read only attribute; it will return some meta information about the - database server to which PDO is connected. - - - - - - PDO::ATTR_CONNECTION_STATUS - (int) - - - +
+ Cursors - - - - - - PDO::ATTR_CASE - (int) - - - - Force column names to a specific case specified by the PDO::CASE_* - constants. - - - - - - PDO::ATTR_CURSOR_NAME - (int) - - - - Get or set the name to use for a cursor. Most useful when using - scrollable cursors and positioned updates. - - - - - - PDO::ATTR_CURSOR - (int) - - - - Selects the cursor type. PDO currently supports either - PDO::CURSOR_FWDONLY and - PDO::CURSOR_SCROLL. Stick with - PDO::CURSOR_FWDONLY unless you know that you need a - scrollable cursor. - - - + + See also PDO::ATTR_CURSOR_NAME. + - - - PDO::ATTR_DRIVER_NAME - (int) - - - - Returns the name of the driver. - - - using <constant>PDO::ATTR_DRIVER_NAME</constant> - -getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') { - echo "Running on mysql; doing something mysql specific here\n"; -} -?> -]]> - - - - - - - - PDO::ATTR_ORACLE_NULLS - (int) - - - - Convert empty strings to SQL NULL values on data fetches. - - - - - - PDO::ATTR_PERSISTENT - (int) - - - - Request a persistent connection, rather than creating a new connection. - See Connections and Connection - management for more information on this attribute. - - - - - - PDO::ATTR_STATEMENT_CLASS - (int) - - - - Sets the class name of which statements are returned as. - - - - - - PDO::ATTR_FETCH_CATALOG_NAMES - (int) - - - - 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. - - - - - - PDO::ATTR_FETCH_TABLE_NAMES - (int) - - - - 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. - - - - - - PDO::ATTR_STRINGIFY_FETCHES - (int) - - - - Forces all fetched values (except &null;) to be treated as strings. - &null; values remain unchanged unless PDO::ATTR_ORACLE_NULLS - is set to PDO::NULL_TO_STRING. - - - - - - PDO::ATTR_MAX_COLUMN_LEN - (int) - - - - Sets the maximum column name length. - - - - - - PDO::ATTR_DEFAULT_FETCH_MODE - (int) - - - + + + + PDO::FETCH_ORI_NEXT + (int) + + + + Fetch the next row in the result set. Valid only for scrollable cursors. + + + + + + PDO::FETCH_ORI_PRIOR + (int) + + + + Fetch the previous row in the result set. Valid only for scrollable + cursors. + + + + + + PDO::FETCH_ORI_FIRST + (int) + + + + Fetch the first row in the result set. Valid only for scrollable cursors. + + + + + + PDO::FETCH_ORI_LAST + (int) + + + + Fetch the last row in the result set. Valid only for scrollable cursors. + + + + + + PDO::FETCH_ORI_ABS + (int) + + + + Fetch the requested row by row number from the result set. Valid only + for scrollable cursors. + + + + + + PDO::FETCH_ORI_REL + (int) + + + + Fetch the requested row by relative position from the current position + of the cursor in the result set. Valid only for scrollable cursors. + + + + + + PDO::CURSOR_FWDONLY + (int) + + + + Create a PDOStatement 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. + + + + + + PDO::CURSOR_SCROLL + (int) + + + + Create a PDOStatement object with a scrollable cursor. Pass the + PDO::FETCH_ORI_* constants to control the rows fetched from the result set. + + + + +
-
-
-
- - - PDO::ATTR_EMULATE_PREPARES - (int) - - - +
+ Other Constants + + + + PDO::PARAM_BOOL + (int) + + + + Represents a boolean data type. + + + + + + PDO::PARAM_NULL + (int) + + + + Represents the SQL NULL data type. + + + + + + PDO::PARAM_INT + (int) + + + + Represents the SQL INTEGER data type. + + + + + + PDO::PARAM_STR + (int) + + + + Represents the SQL CHAR, VARCHAR, or other string data type. + + + + + + PDO::PARAM_STR_NATL + (int) + + + + Flag to denote a string uses the national character set. + + + Available since PHP 7.2.0 + + + + + + PDO::PARAM_STR_CHAR + (int) + + + + Flag to denote a string uses the regular character set. + + + Available since PHP 7.2.0 + + + + + + PDO::PARAM_LOB + (int) + + + + Represents the SQL large object data type. + + + + + + PDO::PARAM_STMT + (int) + + + + Represents a recordset type. Not currently supported by any drivers. + + + + + + PDO::PARAM_INPUT_OUTPUT + (int) + + + + 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. + + + + + + PDO::ATTR_AUTOCOMMIT + (int) + + + + If this value is &false;, PDO attempts to disable autocommit so that the + connection begins a transaction. + + + + + + PDO::ATTR_PREFETCH + (int) + + + + 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. + + + + + + PDO::ATTR_TIMEOUT + (int) + + + + Sets the timeout value in seconds for communications with the database. + + + + + + PDO::ATTR_ERRMODE + (int) + + + + See the Errors and error + handling section for more information about this attribute. + + + + + + PDO::ATTR_SERVER_VERSION + (int) + + + + This is a read only attribute; it will return information about the + version of the database server to which PDO is connected. + + + + + + PDO::ATTR_CLIENT_VERSION + (int) + + + + This is a read only attribute; it will return information about the + version of the client libraries that the PDO driver is using. + + + + + + PDO::ATTR_SERVER_INFO + (int) + + + + This is a read only attribute; it will return some meta information about the + database server to which PDO is connected. + + + + + + PDO::ATTR_CONNECTION_STATUS + (int) + + + - - - - - - PDO::ATTR_DEFAULT_STR_PARAM - (int) - - - - Sets the default string parameter type, this can be one of PDO::PARAM_STR_NATL - and PDO::PARAM_STR_CHAR. - - - Available since PHP 7.2.0. - - - - - - PDO::ERRMODE_SILENT - (int) - - - - 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 Errors and error handling - for more information about this attribute. - - - - - - PDO::ERRMODE_WARNING - (int) - - - - Issue a PHP E_WARNING message if an error occurs. - See Errors and error handling - for more information about this attribute. - - - - - - PDO::ERRMODE_EXCEPTION - (int) - - - - Throw a PDOException if an error occurs. - See Errors and error handling - for more information about this attribute. - - - - - - PDO::CASE_NATURAL - (int) - - - - Leave column names as returned by the database driver. - - - - - - PDO::CASE_LOWER - (int) - - - - Force column names to lower case. - - - - - - PDO::CASE_UPPER - (int) - - - - Force column names to upper case. - - - - - - PDO::NULL_NATURAL - (int) - - - + + + + + + PDO::ATTR_CASE + (int) + + + + Force column names to a specific case specified by the PDO::CASE_* + constants. + + + + + + PDO::ATTR_CURSOR_NAME + (int) + + + + Get or set the name to use for a cursor. Most useful when using + scrollable cursors and positioned updates. + + + + + + PDO::ATTR_CURSOR + (int) + + + + Selects the cursor type. PDO currently supports either + PDO::CURSOR_FWDONLY and + PDO::CURSOR_SCROLL. Stick with + PDO::CURSOR_FWDONLY unless you know that you need a + scrollable cursor. + + + - - - - - - PDO::NULL_EMPTY_STRING - (int) - - - + + + PDO::ATTR_DRIVER_NAME + (int) + + + + Returns the name of the driver. + + + using <constant>PDO::ATTR_DRIVER_NAME</constant> + + getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') { + echo "Running on mysql; doing something mysql specific here\n"; + } + ?> + ]]> + + + + + + + + PDO::ATTR_ORACLE_NULLS + (int) + + + + Convert empty strings to SQL NULL values on data fetches. + + + + + + PDO::ATTR_PERSISTENT + (int) + + + + Request a persistent connection, rather than creating a new connection. + See Connections and Connection + management for more information on this attribute. + + + + + + PDO::ATTR_STATEMENT_CLASS + (int) + + + + Sets the class name of which statements are returned as. + + + + + + PDO::ATTR_FETCH_CATALOG_NAMES + (int) + + + + 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. + + + + + + PDO::ATTR_FETCH_TABLE_NAMES + (int) + + + + 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. + + + + + + PDO::ATTR_STRINGIFY_FETCHES + (int) + + + + Forces all fetched values (except &null;) to be treated as strings. + &null; values remain unchanged unless PDO::ATTR_ORACLE_NULLS + is set to PDO::NULL_TO_STRING. + + + + + + PDO::ATTR_MAX_COLUMN_LEN + (int) + + + + Sets the maximum column name length. + + + + + + PDO::ATTR_DEFAULT_FETCH_MODE + (int) + + + - - - - - - PDO::NULL_TO_STRING - (int) - - - + + + + + + PDO::ATTR_EMULATE_PREPARES + (int) + + + - - - - - - PDO::FETCH_ORI_NEXT - (int) - - - - Fetch the next row in the result set. Valid only for scrollable cursors. - - - - - - PDO::FETCH_ORI_PRIOR - (int) - - - - Fetch the previous row in the result set. Valid only for scrollable - cursors. - - - - - - PDO::FETCH_ORI_FIRST - (int) - - - - Fetch the first row in the result set. Valid only for scrollable cursors. - - - - - - PDO::FETCH_ORI_LAST - (int) - - - - Fetch the last row in the result set. Valid only for scrollable cursors. - - - - - - PDO::FETCH_ORI_ABS - (int) - - - - Fetch the requested row by row number from the result set. Valid only - for scrollable cursors. - - - - - - PDO::FETCH_ORI_REL - (int) - - - - Fetch the requested row by relative position from the current position - of the cursor in the result set. Valid only for scrollable cursors. - - - - - - PDO::CURSOR_FWDONLY - (int) - - - - Create a PDOStatement 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. - - - - - - PDO::CURSOR_SCROLL - (int) - - - - Create a PDOStatement object with a scrollable cursor. Pass the - PDO::FETCH_ORI_* constants to control the rows fetched from the result set. - - - - - - PDO::ERR_NONE - (string) - - - - 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 PDO::errorCode or - PDOStatement::errorCode 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. - - - - - - PDO::PARAM_EVT_ALLOC - (int) - - - - Allocation event - - - - - - PDO::PARAM_EVT_FREE - (int) - - - - Deallocation event - - - - - - PDO::PARAM_EVT_EXEC_PRE - (int) - - - - Event triggered prior to execution of a prepared statement. - - - - - - PDO::PARAM_EVT_EXEC_POST - (int) - - - - Event triggered subsequent to execution of a prepared statement. - - - - - - PDO::PARAM_EVT_FETCH_PRE - (int) - - - - Event triggered prior to fetching a result from a resultset. - - - - - - PDO::PARAM_EVT_FETCH_POST - (int) - - - - Event triggered subsequent to fetching a result from a resultset. - - - - - - PDO::PARAM_EVT_NORMALIZE - (int) - - - - Event triggered during bound parameter registration - allowing the driver to normalize the parameter name. - - - - - - PDO::SQLITE_DETERMINISTIC - (int) - - - - Specifies that a function created with PDO::sqliteCreateFunction - 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.) - - - - + + + + + + PDO::ATTR_DEFAULT_STR_PARAM + (int) + + + + Sets the default string parameter type, this can be one of PDO::PARAM_STR_NATL + and PDO::PARAM_STR_CHAR. + + + Available since PHP 7.2.0. + + + + + + PDO::ERRMODE_SILENT + (int) + + + + 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 Errors and error handling + for more information about this attribute. + + + + + + PDO::ERRMODE_WARNING + (int) + + + + Issue a PHP E_WARNING message if an error occurs. + See Errors and error handling + for more information about this attribute. + + + + + + PDO::ERRMODE_EXCEPTION + (int) + + + + Throw a PDOException if an error occurs. + See Errors and error handling + for more information about this attribute. + + + + + + PDO::CASE_NATURAL + (int) + + + + Leave column names as returned by the database driver. + + + + + + PDO::CASE_LOWER + (int) + + + + Force column names to lower case. + + + + + + PDO::CASE_UPPER + (int) + + + + Force column names to upper case. + + + + + + PDO::NULL_NATURAL + (int) + + + + + + + + + + PDO::NULL_EMPTY_STRING + (int) + + + + + + + + + + PDO::NULL_TO_STRING + (int) + + + + + + + + + + PDO::ERR_NONE + (string) + + + + 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 PDO::errorCode or + PDOStatement::errorCode 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. + + + + + + PDO::PARAM_EVT_ALLOC + (int) + + + + Allocation event + + + + + + PDO::PARAM_EVT_FREE + (int) + + + + Deallocation event + + + + + + PDO::PARAM_EVT_EXEC_PRE + (int) + + + + Event triggered prior to execution of a prepared statement. + + + + + + PDO::PARAM_EVT_EXEC_POST + (int) + + + + Event triggered subsequent to execution of a prepared statement. + + + + + + PDO::PARAM_EVT_FETCH_PRE + (int) + + + + Event triggered prior to fetching a result from a resultset. + + + + + + PDO::PARAM_EVT_FETCH_POST + (int) + + + + Event triggered subsequent to fetching a result from a resultset. + + + + + + PDO::PARAM_EVT_NORMALIZE + (int) + + + + Event triggered during bound parameter registration + allowing the driver to normalize the parameter name. + + + + + + PDO::SQLITE_DETERMINISTIC + (int) + + + + Specifies that a function created with PDO::sqliteCreateFunction + 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.) + + + + +