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 (but not overridden), the inherited method will now share static variables with the parent method. class A { public static function counter() { static $counter = 0; $counter++; return $counter; } } class B extends A {} var_dump(A::counter()); // int(1) var_dump(A::counter()); // int(2) var_dump(B::counter()); // int(3), previously int(1) var_dump(B::counter()); // int(4), previously int(2) This means that static variables in methods now behave the same way as static properties. RFC: https://wiki.php.net/rfc/static_variable_inheritance . Most non-final internal methods now require overriding methods to declare a compatible return type, otherwise a deprecated notice is emitted during inheritance validation. In case the return type cannot be declared for an overriding method due to PHP cross-version compatibility concerns, a `#[ReturnTypeWillChange]` attribute can be added to silence the deprecation notice. RFC: https://wiki.php.net/rfc/internal_method_return_types - Fileinfo: . The fileinfo functions now accept and return, respectively, finfo objects instead of resources. Return value checks using is_resource() should be replaced with checks for `false`. - FTP: . The FTP functions now accept and return, respectively, FTP\Connection objects instead of resources. Return value checks using is_resource() should be replaced with checks for `false`. - IMAP: . The IMAP functions now accept and return, respectively, IMAP\Connection objects instead of resources. Return value checks using is_resource() should be replaced with checks for `false`. - LDAP: . The LDAP functions now accept and return, respectively, LDAP\Connection 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, LDAP\Result 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, LDAP\ResultEntry 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 . Classes extending mysqli_stmt::execute() will be required to specify the additional parameter now. RFC: https://wiki.php.net/rfc/mysqli_bind_in_execute . mysqli::connect() will now return true instead of null on success. - MySQLnd: . The mysqlnd.fetch_data_copy ini setting has been removed. However, this should not result in user-visible behavior changes. - OpenSSL: . EC private keys will now be exported in PKCS#8 format rather than traditional format, just like all other keys. . openssl_pkcs7_encrypt() and openssl_cms_encrypt() will now default to using AES-128-CBC rather than RC2-40. The RC2-40 cipher is considered insecure and not enabled by default in OpenSSL 3. - 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_STRINGIFY_FETCHES option. - PgSQL: . The PgSQL functions now accept and return, respectively, \PgSql\Connection objects instead of "pgsql link" resources. Return value checks using is_resource() should be replaced with checks for `false`. . The PgSQL functions now accept and return, respectively, \PgSql\Result objects instead of "pgsql result" resources. Return value checks using is_resource() should be replaced with checks for `false`. . The PgSQL functions now accept and return, respectively, \PgSql\Lob objects instead of "pgsql large object" resources. Return value checks using is_resource() should be replaced with checks for `false`. - Phar: . To comply with the ArrayAccess interface, Phar::offsetUnset() and PharData::offsetUnset() no longer return a boolean. - PSpell: . The PSpell functions now accept and return, respectively, PSpell\Dictionary objects instead of "pspell" resources. Return value checks using is_resource() should be replaced with checks for `false`. . The PSpell functions now accept and return, respectively, PSpell\Config objects instead of "pspell config" resources. Return value checks using is_resource() should be replaced with checks for `false`. - Standard: . version_compare() no longer accepts undocumented operator abbreviations. . htmlspecialchars(), htmlentities(), htmlspecialchars_decode(), html_entity_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 now print "interned" instead of a dummy refcount of one for interned strings and immutable arrays. - SPL: . SplFixedArray will now be JSON encoded like an array. ======================================== 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 . Added support for never return type RFC: https://wiki.php.net/rfc/noreturn_type . Added support for fibers. RFC: https://wiki.php.net/rfc/fibers . It is now possible to use "new ClassName()" expressions as parameter default values, static variable and global constant initializers, as well as attribute arguments. Objects can also be passed to `define()` now. RFC: https://wiki.php.net/rfc/new_in_initializers . Closures for callables can now be created using the syntax `myFunc(...)`, which is the same as `Closure::fromCallable('myFunc')`. Yes, the `...` is part of the syntax, not an omission. RFC: https://wiki.php.net/rfc/first_class_callable_syntax . File uploads now provide an additional full_path key, which contains the full path (rather than just the basename) of the uploaded file. This is intended for use in conjunction with "upload webkitdirectory". . It is now allowed to specify named arguments after an argument unpack, e.g. foo(...$args, named: $arg). . Added support for intersection types. They cannot be combined with union types. RFC: https://wiki.php.net/rfc/pure-intersection-types . Added support for the final modifier for class constants. RFC: https://wiki.php.net/rfc/final_class_const . Added support for readonly properties. RFC: https://wiki.php.net/rfc/readonly_properties_v2 - Curl: . Added CURLOPT_DOH_URL option. . Added certificate blob options when for libcurl >= 7.71.0: CURLOPT_ISSUERCERT_BLOB CURLOPT_PROXY_ISSUERCERT CURLOPT_PROXY_ISSUERCERT_BLOB CURLOPT_PROXY_SSLCERT_BLOB CURLOPT_PROXY_SSLKEY_BLOB CURLOPT_SSLCERT_BLOB CURLOPT_SSLKEY_BLOB . 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. - GD: . Avif support is now available through the imagecreatefromavif() and imageavif() functions, if libgd has been built with avif support. - hash: . The following functions have changed signatures, to support an optional `$options` argument: - 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 platform 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. . Binding in execute has been added to mysqli prepared statements. Parameters can now be passed to mysqli_stmt::execute as an array. RFC: https://wiki.php.net/rfc/mysqli_bind_in_execute . A new method has been added to mysqli_result called mysqli_fetch_column(). It allows for fetching single scalar values from the result set. RFC: https://wiki.php.net/rfc/mysqli_fetch_column - 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. - Standard: . fputcsv() now accepts a new "eol" argument which allow to define a custom eol sequence, the default remains the same and is "\n". - SPL: . SplFileObject::fputcsv() now accepts a new "eol" argument which allow to define a custom eol sequence, the default remains the same and is "\n". ======================================== 3. Changes in SAPI modules ======================================== - CLI: . Using -a without the readline extension will now result in an error. Previously, -a without readline had the same behavior as calling php without any arguments, apart from printing an additional "Interactive mode enabled" message. This mode was not, in fact, interactive. - phpdbg: . Remote functionality from phpdbg has been removed. ======================================== 4. Deprecated Functionality ======================================== - Core: . Implementing the Serializable interface without also implementing __serialize() and __unserialize() has been deprecated. You should either implement the new methods (if you only support PHP 7.4 and higher) or implement both (if you support older PHP versions as well). RFC: https://wiki.php.net/rfc/phase_out_serializable . Implicit conversion of floats to integers that result in loss of precision, e.g. a truncation from 1.9 to 1, is deprecated. This affects array keys, int parameter and return types, and operators working on integers. RFC: https://wiki.php.net/rfc/implicit-float-int-deprecate . Calling a static method or accessing a static property directly on a trait is deprecated. Static methods and properties should only be accessed on a class using the trait. RFC: https://wiki.php.net/rfc/deprecations_php_8_1 . Returning a non-array from __sleep will raise a warning . Returning by reference from a void function is deprecated. RFC: https://wiki.php.net/rfc/deprecations_php_8_1 . Automatic conversion of "false" into an empty array on write operands is deprecated. RFC: https://wiki.php.net/rfc/autovivification_false - Ctype: . Passing a non-string value to ctype_*() functions is deprecated. A future version of PHP will make ctype_*() accept a string argument, which means that either only strings will be accepted (strict_types=1) or inputs may be converted to string (strict_types=0). In particular, using ctype_*($cp) to check whether an ASCII codepoint given as integer satisfies a given ctype predicate will no longer be supported. Instead ctype_*(chr($cp)) should be used. RFC: https://wiki.php.net/rfc/deprecations_php_8_1 - Date: . The date_sunrise() and date_sunset() functions have been deprecated in favor of date_sun_info(). RFC: https://wiki.php.net/rfc/deprecations_php_8_1 . The strftime() and gmstrftime() functions have been deprecated in favor of date()/DateTime::format() (for locale-independent formatting) or IntlDateFormatter::format() (for locale-dependent formatting). - Filter: . The FILTER_SANITIZE_STRING and FILTER_SANITIZE_STRIPPED filters have been deprecated. RFC: https://wiki.php.net/rfc/deprecations_php_8_1 . The filter.default ini setting is deprecated. RFC: https://wiki.php.net/rfc/deprecations_php_8_1 - GD: . The $num_points parameter of image(open|filled)polygon has been deprecated. - Hash: . The mhash(), mhash_keygen_s2k(), mhash_count(), mhash_get_block_size() and mhash_get_hash_name() functions are deprecated. Use the hash_*() APIs instead. RFC: https://wiki.php.net/rfc/deprecations_php_8_1 - IMAP: . The NIL constant has been deprecated. Use 0 instead. RFC: https://wiki.php.net/rfc/deprecations_php_8_1 - Intl: . Calling IntlCalendar::roll() with bool argument is deprecated. Pass 1 and -1 instead of true and false respectively. RFC: https://wiki.php.net/rfc/deprecations_php_8_1 - Mbstring: . Calling mb_check_encoding() without an argument is deprecated. RFC: https://wiki.php.net/rfc/deprecations_php_8_1 - 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. . The mysqli::init() method has been deprecated. Replace calls to parent::init() with parent::__construct(). RFC: https://wiki.php.net/rfc/deprecations_php_8_1 - OCI8: . The INI directive oci8.old_oci_close_semantics has been deprecated. - ODBC: . odbc_result_all() has been deprecated. RFC: https://wiki.php.net/rfc/deprecations_php_8_1 - PDO: . The PDO::FETCH_SERIALIZE mode has been deprecated. RFC: https://wiki.php.net/rfc/phase_out_serializable - PgSQL: . Not passing the connection argument to PgSQL functions and using the default connection is deprecated. RFC: https://wiki.php.net/rfc/deprecations_php_8_1 - SOAP: . The ssl_method option for the SoapClient constructor has been deprecated in favor of ssl stream context options. The direct equivalent would be crypto_method, but min_proto_version/max_proto_version are recommended instead. RFC: https://wiki.php.net/rfc/deprecations_php_8_1 - Standard: . Calling key(), current(), next(), prev(), reset(), or end() on objects is deprecated. Instead cast the object to array first, or make use of ArrayIterator. RFC: https://wiki.php.net/rfc/deprecations_php_8_1 . The strptime() function has been deprecated. Use date_parse_from_format() instead (for locale-independent parsing) or IntlDateFormatter::parse() (for locale-dependent parsing). RFC: https://wiki.php.net/rfc/deprecations_php_8_1 . The auto_detect_line_endings ini setting has been deprecated. If necessary, handle "\r" line breaks manually instead. RFC: https://wiki.php.net/rfc/deprecations_php_8_1 . The FILE_BINARY and FILE_TEXT constants are deprecated. They already had no effect previously. RFC: https://wiki.php.net/rfc/deprecations_php_8_1 ======================================== 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 properties in zend_object 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 - MBString . mb_check_encoding() now checks input encoding more strictly. . mb_detect_encoding() now checks input encoding more strictly when strict detection is enabled. . mb_convert_encoding() checks the input encoding more strictly if multiple encodings are passed to from_encoding and the mbstring.strict_detection INI directive is set to 1. This change only affects the encoding selection, not the result of the conversion. - PDO ODBC: . PDO::getAttributes() with PDO::ATTR_SERVER_INFO and PDO::ATTR_SERVER_VERSION now return values instead of throwing PDOException. - Reflection: . ReflectionProperty::setAccessible() and ReflectionMethod::setAccessible() no longer have an effect. Properties and methods are always considered accessible through reflection. RFC: https://wiki.php.net/rfc/make-reflection-setaccessible-no-op - Standard: . syslog() is now binary safe. ======================================== 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 - pcntl: . Added pcntl_rfork for FreeBSD variants - Reflection: . Added ReflectionFunctionAbstract::getClosureUsedVariables - Standard: . Added fsync() and fdatasync(), which instruct the operating system to flush its buffers to physical storage. RFC: https://wiki.php.net/rfc/fsync_function - Sodium: . Added the XChaCha20 stream cipher interface functions: - sodium_crypto_stream_xchacha20() - sodium_crypto_stream_xchacha20_keygen() - sodium_crypto_stream_xchacha20_xor() . Added the Ristretto255 functions, which are available in libsodium 1.0.18. Ristretto is a technique for constructing prime order elliptic curve groups with non-malleable encodings. Ristretto255 implements Ristretto atop Curve25519. - sodium_crypto_core_ristretto255_add() - sodium_crypto_core_ristretto255_from_hash() - sodium_crypto_core_ristretto255_is_valid_point() - sodium_crypto_core_ristretto255_random() - sodium_crypto_core_ristretto255_scalar_add() - sodium_crypto_core_ristretto255_scalar_complement() - sodium_crypto_core_ristretto255_scalar_invert() - sodium_crypto_core_ristretto255_scalar_mul() - sodium_crypto_core_ristretto255_scalar_negate() - sodium_crypto_core_ristretto255_scalar_random() - sodium_crypto_core_ristretto255_scalar_reduce() - sodium_crypto_core_ristretto255_scalar_sub() - sodium_crypto_core_ristretto255_sub() - sodium_crypto_scalarmult_ristretto255() - sodium_crypto_scalarmult_ristretto255_base() ======================================== 7. New Classes and Interfaces ======================================== - Intl: . Added IntlDatePatternGenerator to dynamically generate patterns to use with IntlDateFormatter. RFC: https://wiki.php.net/rfc/intldatetimepatterngenerator ======================================== 8. Removed Extensions and SAPIs ======================================== ======================================== 9. Other Changes to Extensions ======================================== - GD: imagewebp() can do lossless WebP encoding by passing IMG_WEBP_LOSSLESS as quality. This constant is only defined, if a libgd is used which supports lossless WebP encoding. - Mbstring: . Unicode data tables have been updated to Unicode 14. - 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. . OpenSSL 3.0 is now supported. Be aware that many ciphers are no longer enabled by default (part of the legacy provider), and that parameter validation (e.g. minimum key sizes) is stricter now. - Phar: . Use SHA256 by default for signature. . Add support for OpenSSL_SHA256 and OpenSSL_SHA512 signature. - SNMP: . add SHA256 and SHA512 for security protocol. - 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. . --with-external-libcrypt now allows to use system libcrypt/libxcrypt instead in PHP own implementation. ======================================== 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. - Sockets: . The following socket options are now defined if they are supported: * SO_ACCEPTFILTER * SO_DONTTRUNC * SO_WANTMORE * SO_MARK * TCP_DEFER_ACCEPT ======================================== 11. Changes to INI File Handling ======================================== - The log_errors_max_len ini setting has been removed. It no longer had an effect since PHP 8.0. - A leading dollar in a quoted string can now be escaped: "\${" will now be interpreted as a string with contents `${`. - Backslashes in double quoted strings are now more consistently treated as escape characters. Previously, "foo\\" followed by something other than a newline was not considered as a teminated string. It is now interpreted as a string with contents `foo\`. However, as an exception, the string "foo\" followed by a newline will continue to be treated as a valid string with contents `foo\` rather than an unterminated string. This exception exists to support naive uses of Windows file pahts as "C:\foo\". ======================================== 12. Windows Support ======================================== ======================================== 13. Other Changes ======================================== ======================================== 14. Performance Improvements ========================================