From 9a4ec4015ab8c5d02df77b91ad4f9e09ec6dddd0 Mon Sep 17 00:00:00 2001 From: Gina Peter Banyard Date: Tue, 15 Oct 2024 19:38:19 +0100 Subject: [PATCH] [skip ci] Group similar entries in UPGRADING (#16420) * [skip ci] Group similar entries in UPGRADING This groups together: - Class constants being typed - Resource to object conversions - New warnings and exceptions Drive-by wording improvements --------- Co-authored-by: Christoph M. Becker --- UPGRADING | 217 ++++++++++++++++++++++++++---------------------------- 1 file changed, 103 insertions(+), 114 deletions(-) diff --git a/UPGRADING b/UPGRADING index a683113c8d719..a200bac03d947 100644 --- a/UPGRADING +++ b/UPGRADING @@ -40,13 +40,108 @@ PHP 8.4 UPGRADE NOTES removed. RFC: https://wiki.php.net/rfc/deprecations_php_8_4#remove_e_strict_error_level_and_deprecate_e_strict_constant -- Date: - . The class constants are typed now. - -- DBA: - . dba_open() and dba_popen() will now return a Dba\Connection - object rather than a resource. Return value checks using is_resource() - should be replaced with checks for `false`. +- Extension Class constants are now typed: + . Date + . Intl + . PDO + . Reflection + . SPL + . Sqlite + . XMLReader + +- Resource to Object conversions: + Return value checks using is_resource() should be replaced with checks + for `false`, unless specified otherwise. + . DBA: + . dba_open() and dba_popen() will now return Dba\Connection + . ODBC: + . odbc_connect() and odbc_pconnect() will now return Odbc\Connection + . odbc_prepare(), odbc_exec(), and various other functions will now return + Odbc\Result + . SOAP: + . SoapClient::$httpurl is now a Soap\Url object rather than a resource. + Checks using is_resource() (i.e. is_resource($client->httpurl)) should be + replaced with checks for null (i.e. $client->httpurl !== null). + . SoapClient::$sdl is now a Soap\Sdl object rather than a resource. + Checks using is_resource() (i.e. is_resource($client->sdl)) should be + replaced with checks for null (i.e. $client->sdl !== null). + +- New warnings and exceptions: + . Curl: + . curl_multi_select throws a ValueError if the timeout argument if it's negative + or greater than PHP_INT_MAX. + . GD: + . imagejpeg/imagewebp/imagepng/imageavif throws an exception if an invalid + quality parameter value is passed. In addition, imageavif will throw an exception + if an invalid speed parameter value is passed. + . imagescale throws an exception if the width/height argument underflows/overflows or + if the mode argument is invalid. + imagefilter with IMG_FILTER_SCATTER throws an exception if the sub/plus arguments + underflows/overflows. + . Gettext: + . bind_textdomain_codeset, textdomain and d(*)gettext functions now throw an exception + if the domain argument is empty. + . Intl: + . resourcebundle_get(), ResourceBundle::get(), and accessing offsets on a + ResourceBundle object now throw: + - TypeError for invalid offset types + - ValueError for an empty string + - ValueError if the integer index does not fit in a signed 32 bit integer + . IntlDateFormatter::__construct() throws a ValueError if the locale is invalid. + . NumberFormatter::__construct() throws a ValueError if the locale is invalid. + . MBString: + . mb_encode_numericentity() and mb_decode_numericentity() now check that + the $map is only composed of integers, if not a ValueError is thrown. + . mb_http_input() now always throws a ValueError if the $type is invalid. + . mb_http_output() now checks that the $encoding parameter does not + contain any null bytes. If it does, a ValueError is now thrown. + . ODBC: + . odbc_fetch_row() now emits a warning when a value less than or equal to 0 is + passed for parameter $row. + . PCNTL: + . The functions pcntl_sigprocmask(), pcntl_sigwaitinfo() and + pcntl_sigtimedwait() now throw: + - A ValueError if the $signals array is empty (except for + pcntl_sigprocmask() if the $mode is SIG_SETMASK). + - A TypeError if a value of the $signals array is not an integer + - A ValueError if a value of the $signals array is not a valid signal number + . The function pcntl_sigprocmask() now throw: + - A ValueError if $mode is not one of SIG_BLOCK, SIG_UNBLOCK, or SIG_SETMASK + . The function pcntl_sigtimedwait() now throw: + - A ValueError if $seconds is less than 0 + - A ValueError if $nanoseconds is less than 0 or greater than 1e9 + - A ValueError if both $seconds and $nanoseconds are 0 + . SimpleXML: + . Calling simplexml_import_dom() with a non-XML object now throws a + TypeError instead of a ValueError. + . Standard: + . round() now validates the value of the $mode parameter and throws a + ValueError for invalid modes. Previously invalid modes would have been + interpreted as PHP_ROUND_HALF_UP. + . The str_getcsv() function now throws ValueErrors when the $separator and + $enclosure arguments are not one byte long, or if the $escape is not one + byte long or the empty string. This aligns the behaviour to be identical + to that of fputcsv() and fgetcsv(). + . php_uname() now throws ValueErrors if the $move parameter is invalid. + . The "allowed_classes" option for unserialize() now throws TypeErrors and + ValueErrors if it is not an array of class names. + . XMLReader: + . Passing an invalid character encoding to XMLReader::open() or + XMLReader::XML() now throws a ValueError. + . Passing a string containing null bytes previously emitted a + warning and now throws a ValueError as well. + . XMLWriter: + . Passing a string containing null bytes previously emitted a + warning and now throws a ValueError as well. + . XSL: + . XSLTProcessor::setParameter() will now throw a ValueError when its + arguments contain null bytes. This never actually worked correctly in + the first place, which is why it throws an exception nowadays. + . Calling XSLTProcessor::importStyleSheet() with a non-XML object now + throws a TypeError instead of a ValueError. + . Failure to call a PHP function callback during evaluation now throws + instead of emitting a warning. + RFC: https://wiki.php.net/rfc/improve_callbacks_dom_and_xsl - DOM: . Some DOM methods previously returned false or a PHP_ERR DOMException if a new @@ -64,20 +159,7 @@ PHP 8.4 UPGRADE NOTES . The GMP class is now final and cannot be extended anymore. RFC: https://wiki.php.net/rfc/gmp-final -- Intl: - . resourcebundle_get(), ResourceBundle::get(), and accessing offsets on a - ResourceBundle object now throw: - - TypeError for invalid offset types - - ValueError for an empty string - - ValueError if the integer index does not fit in a signed 32 bit integer - . The class constants are typed now. - - MBString: - . mb_encode_numericentity() and mb_decode_numericentity() now check that - the $map is only composed of integers, if not a ValueError is thrown. - . mb_http_input() now always throws a ValueError if the $type is invalid. - . mb_http_output() now checks that the $encoding parameter does not - contain any null bytes. If it does, a ValueError is now thrown. . On invalid strings (those with encoding errors), mb_substr() now interprets character indices in the same manner as most other mbstring functions. This means that character indices returned by mb_strpos() can be passed to mb_substr(). @@ -103,16 +185,6 @@ PHP 8.4 UPGRADE NOTES . The error code reported for MySQL server wait timeouts has been changed from 2006 to 4031 for MySQL server versions 8.0.24 and above. -- ODBC: - . odbc_fetch_row() returns false when a value less than or equal to 0 is - passed for parameter $row. Now, a warning is emitted in this case. - . odbc_connect() and odbc_pconnect() will now return an Odbc\Connection - object rather than a resource. Return value checks using is_resource() - should be replaced with checks for `false`. - . odbc_prepare(), odbc_exec(), and various other functions will now return - an Odbc\Result object rather than a resource. Return value checks using - is_resource() should be replaced with checks for `false`. - - Opcache: . The JIT config defaults changed from opcache.jit=tracing and opcache.jit_buffer_size=0 to opcache.jit=disable and @@ -129,19 +201,8 @@ PHP 8.4 UPGRADE NOTES - PCNTL: . The functions pcntl_sigprocmask(), pcntl_sigwaitinfo() and - pcntl_sigtimedwait() now throw: - - A ValueError if the $signals array is empty (except for - pcntl_sigprocmask() if the $mode is SIG_SETMASK). - - A TypeError if a value of the $signals array is not an integer - - A ValueError if a value of the $signals array is not a valid signal number - Moreover, those functions now always return false on failure. + pcntl_sigtimedwait() now always return false on failure. In some case previously it could return the value -1. - . The function pcntl_sigprocmask() will also now throw: - - A ValueError if $mode is not one of SIG_BLOCK, SIG_UNBLOCK, or SIG_SETMASK - . The function pcntl_sigtimedwait() will also now throw: - - A ValueError if $seconds is less than 0 - - A ValueError if $nanoseconds is less than 0 or greater than 1e9 - - A ValueError if both $seconds and $nanoseconds are 0 - PCRE: . The bundled pcre2lib has been updated to version 10.44. @@ -150,9 +211,6 @@ PHP 8.4 UPGRADE NOTES has changed. Consult https://github.com/PCRE2Project/pcre2/blob/master/NEWS for a full changelog. -- PDO: - . The class constants are typed now. - - PDO_DBLIB: . setAttribute, DBLIB_ATTR_STRINGIFY_UNIQUEIDENTIFIER and DBLIB_ATTR_DATETIME_CONVERT have been changed to set value as a bool. @@ -166,17 +224,11 @@ PHP 8.4 UPGRADE NOTES - PDO_MYSQL: . getAttribute, ATTR_AUTOCOMMIT, ATTR_EMULATE_PREPARES, MYSQL_ATTR_DIRECT_QUERY have been changed to get values as bool. - . Quoting a string with PARAM_LOB as type now outputs the string explicitly quoted - as binary. This also affects parameters bound as PARAM_LOB when - ATTR_EMULATE_PREPARES is enabled. - PDO_PGSQL: . The DSN's credentials, when set, are given priority over their PDO constructor counterparts, being closer to the documentation states. -- Reflection: - . The class constants are typed now. - - SimpleXML: . Get methods called, or casting to a string on a SimpleXMLElement will no longer implicitly reset the iterator data, unless explicitly rewound. @@ -184,16 +236,8 @@ PHP 8.4 UPGRADE NOTES cause an infinite loop because it destroyed the current iterator data. This is no longer the case as a consequence of the bugfixes for GH-12192, GH-12208, #55098. - . Calling simplexml_import_dom() with a non-XML object now throws a TypeError - instead of a ValueError. - SOAP: - . SoapClient::$httpurl is now a Soap\Url object rather than a resource. - Checks using is_resource() (i.e. is_resource($client->httpurl)) should be - replaced with checks for null (i.e. $client->httpurl !== null). - . SoapClient::$sdl is now a Soap\Sdl object rather than a resource. - Checks using is_resource() (i.e. is_resource($client->sdl)) should be - replaced with checks for null (i.e. $client->sdl !== null). . SoapClient::$typemap is now an array rather than a resource. Checks using is_resource() (i.e. is_resource($client->typemap)) should be replaced with checks for null (i.e. $client->typemap !== null). @@ -202,25 +246,9 @@ PHP 8.4 UPGRADE NOTES you will experience errors on startup if you also use the SOAP extension. To solve this, either don't use rtld-now or load the session extension. -- SPL: - . The class constants are typed now. - -- Sqlite: - . The class constants are typed now. - - Standard: - . round() now validates the value of the $mode parameter and throws a ValueError - for invalid modes. Previously invalid modes would have been interpreted as - PHP_ROUND_HALF_UP. . strcspn() with empty $characters now returns the length of the string instead of incorrectly stopping at the first NUL character. See GH-12592. - . The str_getcsv() function now throws ValueErrors when the $separator and - $enclosure arguments are not one byte long, or if the $escape is not one - byte long or the empty string. This aligns the behaviour to be identical - to that of fputcsv() and fgetcsv(). - . php_uname() now throws ValueErrors on invalid inputs. - . The "allowed_classes" option for unserialize() now throws TypeErrors and - ValueErrors if it is not an array of class names. . http_build_query() now correctly handles backed enums. . stream_bucket_make_writeable() and stream_bucket_new() will now return a StreamBucket instance instead of an instance of stdClass. @@ -241,26 +269,6 @@ PHP 8.4 UPGRADE NOTES Passing an empty string to disable the handler is still allowed, but deprecated. -- XMLReader: - . Passing an invalid character encoding to XMLReader::open() or - XMLReader::XML() now throws a ValueError. Passing a string containing NULL - bytes previously emitted a warning and now throws a ValueError as well. - . The class constants are typed now. - -- XMLWriter: - . Passing a string containing NULL bytes previously emitted a warning and - now throws a ValueError. - -- XSL: - . XSLTProcessor::setParameter() will now throw a ValueError when its arguments - contain null bytes. This never actually worked correctly in the first place, - which is why it throws an exception nowadays. - . Failure to call a PHP function callback during evaluation now throws - instead of emitting a warning. - RFC: https://wiki.php.net/rfc/improve_callbacks_dom_and_xsl - . Calling XSLTProcessor::importStyleSheet() with a non-XML object now throws - a TypeError instead of a ValueError. - ======================================== 2. New Features ======================================== @@ -615,34 +623,15 @@ PHP 8.4 UPGRADE NOTES . trigger_error() and user_error() now have a return type of true instead of bool. -- Curl: - . curl_multi_select throws a ValueError if the timeout argument if it's negative - or greater than PHP_INT_MAX. - - DOM: . DOMDocument::registerNodeClass() now has a tentative return type of true. Previously, the return type was bool but only true could be returned in practice. -- GD: - . imagejpeg/imagewebp/imagepng/imageavif throws an exception if an invalid - quality parameter value is passed. In addition, imageavif will throw an exception - if an invalid speed parameter value is passed. - . imagescale throws an exception if the width/height argument underflows/overflows or - if the mode argument is invalid. - imagefilter with IMG_FILTER_SCATTER throws an exception if the sub/plus arguments - underflows/overflows. - -- Gettext: - . bind_textdomain_codeset, textdomain and d(*)gettext functions now throw an exception - if the domain argument is empty. - - Hash: . Changed the return type of hash_update() to true. It was already the case that only true could be returned, but the stub was not updated yet. - Intl: - . IntlDateFormatter::__construct() throws a ValueError if the locale is invalid. - . NumberFormatter::__construct() throws a ValueError if the locale is invalid. . NumberFormatter::ROUND_TOWARD_ZERO and NumberFormatter::ROUND_AWAY_FROM_ZERO have been added as aliases for NumberFormatter::ROUND_DOWN and NumberFormatter::ROUND_UP to be consistent with the new PHP_ROUND_* modes.