[skip ci] Group similar entries in UPGRADING (php#16420)

Girgias · cmb69 · web-flow · commit 9a4ec4015ab8 · 2024-10-15T19:38:19.000+01:00
* [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 &lt;cmbecker69@gmx.de&gt;
diff --git 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,34 +224,20 @@ 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.
     For example, casting an element to a string within a foreach loop would
     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.
