PHP 8.1 UPGRADE NOTES 1. Backward Incompatible Changes 2. New Features 3. Changes in SAPI modules 4. Deprecated Functionality 5. Changed Functions 6. New Functions 7. New Classes and Interfaces 8. Removed Extensions and SAPIs 9. Other Changes to Extensions 10. New Global Constants 11. Changes to INI File Handling 12. Windows Support 13. Other Changes 14. Performance Improvements ======================================== 1. Backward Incompatible Changes ======================================== - Core: . Access to the $GLOBALS array is now subject to a number of restrictions. Read and write access to individual array elements like $GLOBALS['var'] continues to work as-is. Read-only access to the entire $GLOBALS array also continues to be supported. However, write access to the entire $GLOBALS array is no longer supported. For example, array_pop($GLOBALS) will result in an error. RFC: https://wiki.php.net/rfc/restrict_globals_usage . Passing null to a non-nullable argument of a built-in function is deprecated. This matches the behavior of user-defined functions, where null is never accepted by non-nullable arguments. user-defined functions. var_dump(str_contains("foobar", null)); // Deprecated: Passing null to parameter #2 ($needle) of type string // is deprecated RFC: https://wiki.php.net/rfc/deprecate_null_to_scalar_internal_arg . When a method using static variables is inherited, the inherited method will now initialize the static variables to their original values, rather than the values at the time of inheritance: class A { public function counter() { static $counter = 0; $counter++; return $counter; } } var_dump((new A)->counter()); // int(1) eval('class B extends A {}'); // eval() to prevent early binding. var_dump((new B)->counter()); // int(1), previously int(2) var_dump((new A)->counter()); // int(2) var_dump((new B)->counter()); // int(2), previously int(3) Previously the behavior would be different depending on whether A::counter() was called before class B was declared, or after it was declared. - Fileinfo: . The fileinfo functions now accept and return, respectively, finfo objects instead of resources. - IMAP: . The IMAP functions now accept and return, respectively, IMAPConnection objects instead of resources. - LDAP: . The LDAP functions now accept and return, respectively, LDAP objects instead of "ldap link" resources. Return value checks using is_resource() should be replaced with checks for `false`. . The LDAP functions now accept and return, respectively, LDAPResult objects instead of "ldap result" resources. Return value checks using is_resource() should be replaced with checks for `false`. . The LDAP functions now accept and return, respectively, LDAPResultEntry objects instead of "ldap result entry" resources. Return value checks using is_resource() should be replaced with checks for `false`. - MySQLi: . mysqli_fetch_fields() and mysqli_fetch_field_direct() will now always return zero for max_length. You can compute this information by iterating over the result set and taking the maximum length. This is what PHP was doing internally previously. . The MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH option no longer has an effect. . The MYSQLI_STORE_RESULT_COPY_DATA option no longer has an effect. . The default error handling mode has been changed from "silent" to "exceptions". See https://www.php.net/manual/en/mysqli-driver.report-mode.php for details of behavior changes and how to explicitly set this attribute. To keep the old behavior, use mysqli_report(MYSQLI_REPORT_OFF); RFC: https://wiki.php.net/rfc/mysqli_default_errmode - MySQLnd: . The mysqlnd.fetch_copy_data ini setting has been removed. However, this should not result in user-visible behavior changes. - PDO: . PDO::ATTR_STRINGIFY_FETCHES now also stringifies values of type bool to "0" or "1". Previously booleans were not stringified. . Calling bindColumn() with PDO::PARAM_LOB (and assuming stringification is not enabled) will now consistently bind a stream result, as documented. Previously the result would be either a stream or a string depending on the used database driver and the time the binding is performed. - PDO MySQL: . Integers and floats in result sets will now be returned using native PHP types instead of strings when using emulated prepared statements. This matches the behavior of native prepared statements. You can restore the previous behavior by enabling the PDO::ATTR_STRINGIFY_FETCHES option. - PDO SQLite: . Integers and floats in results sets will now be returned using native PHP types. You can restore the previous behavior by enabling the PDO::ATTR_STRINGFIY_FETCHES option. - Standard: . version_compare() no longer accepts undocumented operator abbreviations. . htmlspecialchars(), htmlentities(), htmlspecialchars_decode(), html_entitity_decode() and get_html_translation_table() now use ENT_QUOTES | ENT_SUBSTITUTE rather than ENT_COMPAT by default. This means that ' is escaped to ' while previously it was left alone. Additionally, malformed UTF-8 will be replaced by a Unicode substitution character, instead of resulting in an empty string. . debug_zval_dump() will now print reference wrappers with their refcount, instead of only prepending a "&" to the value. This more accurately models reference representation since PHP 7.0. . debug_zval_dump() will not print "interned" instead of a dummy refcount of one for interned strings and immutable arrays. ======================================== 2. New Features ======================================== - Core: . It is now possible to specify octal integer by using the explicit "0o"/"0O" prefix similar to hexadecimal ("0x"/"0X) and binary ("0b"/"0B") integer literals. RFC: https://wiki.php.net/rfc/explicit_octal_notation . Added support for array unpacking with strings keys. RFC: https://wiki.php.net/rfc/array_unpacking_string_keys . Added support for enumerations. RFC: https://wiki.php.net/rfc/enumerations - Curl: . Added CURLOPT_DOH_URL option. . Added CURLStringFile, which can be used to post a file from a string rather than a file: $file = new CURLStringFile($data, 'filename.txt', 'text/plain'); curl_setopt($curl, CURLOPT_POSTFIELDS, ['file' => $file]); - FPM: . Added openmetrics status format. It can be used by Prometheus to fetch FPM metrics. . Added new pool option for the dynamic process manager called pm.max_spawn_rate. It allows to start number of children in a faster rate when dynamic pm is selected. The default value is 32 which was the previous hard coded value. - hash: . The following functions have changed signatures: - function hash(string $algo, string $data, bool $binary = false, array $options = []): string|false {} - function hash_file(string $algo, string $filename, bool $binary = false, array $options = []): string|false {} - function hash_init(string $algo, int $flags = 0, string $key = "", array $options = []): HashContext {} The additional `$options` argument can be used to pass algorithm specific data. . Added MurmurHash3 with streaming support. The following variants are implemented: - murmur3a, 32-bit hash - murmur3c, 128-bit hash for x86 - murmur3f, 128-bit hash for x64 The initial hash state can be passed through the `seed` key in the `$options` array, for example: ```php $h = hash("murmur3f", $data, options: ["seed" => 42]); echo $h, "\n"; ``` A valid seed value is within the range from 0 to the plaform defined UINT_MAX, usually 4294967295. . Added xxHash. The implementation brings in the following arguments - xxh32, 32-bit hash - xxh64, 64-bit hash - xxh3, 64-bit hash - xxh128, 128-bit hash The initial hash state can be passed through the `seed` key in the `$options` array, for example: ```php $h = hash("xxh3", $data, options: ["seed" => 42]); echo $h, "\n"; ``` Secret usage is supported through passing the `secret` key in the `$options` array, too: ```php $h = hash("xxh3", $data, options: ["secret" => "at least 136 bytes long secret here"]); echo $h, "\n"; ``` Note, that the quality of the custom secret is crucial for the quality of the resulting hash. It is highly recommended for the secret to use the best possible entropy. - MySQLi: . The mysqli.local_infile_directory ini setting has been added, which can be used to specify a directory from which files are allowed to be loaded. It is only meaningful if mysqli.allow_local_infile is not enabled, as all directories are allowed in that case. - PDO MySQL: . The PDO::MYSQL_ATTR_LOCAL_INFILE_DIRECTORY attribute has been added, which can be used to specify a directory from which files are allowed to be loaded. It is only meaningful if PDO::MYSQL_ATTR_LOCAL_INFILE is not enabled, as all directories are allowed in that case. - PDO SQLite: . SQLite's "file:" DSN syntax is now supported, which allows specifying additional flags. This feature is not available if open_basedir is set. Example: new PDO('sqlite:file:path/to/sqlite.db?mode=ro') - Posix: . Added POSIX_RLIMIT_KQUEUES and POSIX_RLIMIT_NPTS. These rlimits are only available on FreeBSD. ======================================== 3. Changes in SAPI modules ======================================== ======================================== 4. Deprecated Functionality ======================================== - MySQLi: . The mysqli_driver::$driver_version property has been deprecated. The driver version is meaningless as it hasn't been updated in more than a decade. Use PHP_VERSION_ID instead. . Calling mysqli::get_client_info in OO style or passing $mysqli argument to mysqli_get_client_info() function has been deprecated. Use mysqli_get_client_info() without any arguments to obtain the client library version information. ======================================== 5. Changed Functions ======================================== - Core: . Properties order used in foreach, var_dump(), serialize(), object comparison etc. was changed. Now properties are naturally ordered according to their declaration and inheritance. Properties declared in a base class are going to be before the child properties. This order is consistent with internal layout of properies in zend_objct structure and repeats the order in default_properties_table[] and properties_info_table[]. The old order was not documented and was caused by class inheritance implementation details. - Filter: . The FILTER_FLAG_ALLOW_OCTAL flag of the FILTER_VALIDATE_INT filter now accept octal string with the leading octal prefix ("0o"/"0O") RFC: https://wiki.php.net/rfc/explicit_octal_notation - GMP: . All GMP function now accept octal string with the leading octal prefix ("0o"/"0O") RFC: https://wiki.php.net/rfc/explicit_octal_notation ======================================== 6. New Functions ======================================== - Core: . Added array_is_list(array $array), which will return true if the array keys are 0 .. count($array)-1 in that order. RFC: https://wiki.php.net/rfc/is_list ======================================== 7. New Classes and Interfaces ======================================== ======================================== 8. Removed Extensions and SAPIs ======================================== ======================================== 9. Other Changes to Extensions ======================================== - MySQLi: . The mysqli_stmt::next_result() and mysqli::fetch_all() methods are now available when linking against libmysqlclient. - OpenSSL: . The OpenSSL extension now requires at least OpenSSL version 1.0.2. - Standard: . --with-password-argon2 now uses pkg-config to detect libargon2. As such, an alternative libargon2 location should now be specified using PKG_CONFIG_PATH. ======================================== 10. New Global Constants ======================================== - MySQLi: . MYSQLI_REFRESH_REPLICA has been added as a replacement for MYSQLI_REFRESH_SLAVE, in line with an upstream change in MySQL. The old constant is still available for backwards-compatibility reasons, but may be deprecated/removed in the future. ======================================== 11. Changes to INI File Handling ======================================== ======================================== 12. Windows Support ======================================== . The macro IGNORE_URL_WIN has been removed; it had no effect as of PHP 5.0.0. ======================================== 13. Other Changes ======================================== ======================================== 14. Performance Improvements ========================================