diff --git a/reference/pdo/constants.fetch-modes.xml b/reference/pdo/constants.fetch-modes.xml index aef9b257f0c2..68f4fed2c118 100644 --- a/reference/pdo/constants.fetch-modes.xml +++ b/reference/pdo/constants.fetch-modes.xml @@ -2,10 +2,10 @@
Fetch Modes - + See cursor constants for the PDO::FETCH_ORI_* cursor constants. - +
Basic Fetch Modes @@ -81,7 +81,7 @@ Use a function to create the return value. - (PDOStatement::fetchAll only) + (PDOStatement::fetchAll only) @@ -108,10 +108,10 @@
PDO::FETCH_CLASS options - + These modes are used to implement options when using PDO::FETCH_CLASS. - + @@ -154,10 +154,10 @@
Single Result Modes - + The following modes cannot be used with - PDOStatement::fetchAll. - + PDOStatement::fetchAll. + @@ -200,14 +200,14 @@
- Special Behavior Flags for <function>PDOStatement::fetchAll</function> + Special Behavior Flags for <methodname>PDOStatement::fetchAll</methodname> - + The following special modes for multiple results only work with - PDOStatement::fetchAll and do not work with some other + PDOStatement::fetchAll and do not work with some other fetch modes. Check the full documentation for details. - + @@ -241,23 +241,23 @@
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 + + It is possible to set 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). - + PDO::__construct or + PDO::setAttribute. + + + The default fetch mode for a specific statement can be set using + PDOStatement::setFetchMode. + This affects reuse as a prepared statement and iteration (using + &foreach;). + - - PDOStatement::setAttribute cannot be used to set the + + 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. - - + + Available as of 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. @@ -318,10 +318,10 @@ JOIN table2 ON table1.table2id = table2.id
PDO::FETCH_ASSOC (<type>int</type>) - + PDO::FETCH_ASSOC returns an array indexed by column name only. - + 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. - + @@ -401,20 +401,20 @@ Array
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. - + 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 *. - + @@ -487,16 +487,16 @@ Array
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 + 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. - + 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. - + only makes sense with PDOStatement::fetchAll. + - + If the first column is not unique, values will be lost. Which value(s) are lost should be considered undefined. - + @@ -569,21 +569,22 @@ Array
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 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. - + with PDOStatement::fetchAll. + + + The function receives the values as parameters. + There's no way to retrieve the column name a given value was associated with. + It is crucial to ensure that the column order in the query matches the + order of parameters of the function. + - + The effects of PDO::FETCH_GROUP and PDO::FETCH_UNIQUE are applied to results before the function is called. - + @@ -641,14 +642,14 @@ Array
PDO::FETCH_OBJ (<type>int</type>) - + PDO::FETCH_OBJ returns a stdClass object. - - - See also PDOStatement::fetchObject and + + + See also PDOStatement::fetchObject and PDO::FETCH_CLASS. - + 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. - + + + See also PDOStatement::fetchObject. + 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. - + 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. - + - + 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. - + @@ -983,20 +984,20 @@ object(TestEntity)#5 (4) {
PDO::FETCH_BOUND (<type>int</type>) - + This fetch mode cannot be used with - PDOStatement::fetchAll. - - + PDOStatement::fetchAll. + + This fetch mode does not directly return a result, but binds values to - variables specified with PDOStatement::bindColumn. The + variables specified with PDOStatement::bindColumn. The called fetch method returns &true;. - + - + When using prepared statements, to work correctly, variables must be bound after the query is executed. - + fetch(\PDO::FETCH_BOUND)) {
PDO::FETCH_INTO (<type>int</type>) - + This fetch mode cannot be used with - PDOStatement::fetchAll. - - + 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 cannot be readonly. - + - + There's no way to change the object to be updated without using - PDOStatement::setFetchMode between retrieving each + PDOStatement::setFetchMode between retrieving each record. - + @@ -1103,34 +1104,34 @@ object(TestEntity)#3 (4) {
PDO::FETCH_LAZY (<type>int</type>) - + This fetch mode cannot be used with - PDOStatement::fetchAll. - - + 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. - + 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. - - + 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. - - + + If no fetch mode from the above list is given, the current default fetch mode for the PDOStatement will be used. - + - - In the above example you'll note that the first column is omitted from the + + In the above example one should 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: - + 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. - - + 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 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. - + @@ -1386,11 +1387,11 @@ Array ]]> - - In the above example you'll note that the first column is omitted from the + + In the above example one should 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: - + Cursors - + See also PDO::ATTR_CURSOR_NAME. - + @@ -104,8 +104,9 @@ - Create a PDOStatement object with a scrollable cursor. Pass the - PDO::FETCH_ORI_* constants to control the rows fetched from the result set. + Create a PDOStatement object with a scrollable cursor. + Pass the PDO::FETCH_ORI_* + constants to control the rows fetched from the result set. @@ -169,7 +170,7 @@ Flag to denote a string uses the national character set. - Available since PHP 7.2.0 + Available as of PHP 7.2.0 @@ -183,7 +184,7 @@ Flag to denote a string uses the regular character set. - Available since PHP 7.2.0 + Available as of PHP 7.2.0 @@ -217,8 +218,8 @@ 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. + procedure. This constant must be bitwise-ORed with one of the + PDO::PARAM_* constants. @@ -241,8 +242,8 @@ - Setting the prefetch size allows you to balance speed against memory - usage for your application. Not all database/driver combinations support + Setting the prefetch size allows balancing speed against memory + usage for an 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. @@ -325,7 +326,8 @@ - Force column names to a specific case specified by the PDO::CASE_* + Force column names to a specific case specified by the + PDO::CASE_* constants. @@ -350,10 +352,10 @@ 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::CURSOR_FWDONLY or + PDO::CURSOR_SCROLL. + Unless one has a need for scrollable cursors, one should use the + PDO::CURSOR_FWDONLY cursor mode. @@ -367,8 +369,8 @@ Returns the name of the driver. - - using <constant>PDO::ATTR_DRIVER_NAME</constant> + + using <constant>PDO::ATTR_DRIVER_NAME</constant> ]]> - - + @@ -427,7 +428,7 @@ 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. + not be supported by the driver in use. @@ -440,8 +441,8 @@ 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. + character. Support of this attribute is at the driver level; it may + not be supported by the driver in use. @@ -502,7 +503,7 @@ and PDO::PARAM_STR_CHAR. - Available since PHP 7.2.0. + Available as of PHP 7.2.0. @@ -513,8 +514,9 @@ - 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. + Do not raise an error or exception if an error occurs. + The developer is expected to explicitly check for errors. + Prior to PHP 8.0.0, this was the default mode. See Errors and error handling for more information about this attribute. @@ -541,6 +543,7 @@ Throw a PDOException if an error occurs. + This is the default mode as of PHP 8.0.0. See Errors and error handling for more information about this attribute. @@ -619,12 +622,14 @@ - 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 + Corresponds to SQLSTATE '00000', meaning that the SQL + statement was successfully issued with no errors or warnings. + This constant is a convenience constant to help 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. + occurred. + This is usually know if when examining the return code from the method + that raised the error condition anyway.