rfc:deprecations_php_8_1

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
rfc:deprecations_php_8_1 [2021/05/17 11:54]
kocsismate
rfc:deprecations_php_8_1 [2021/07/14 07:23]
nikic
Line 1: Line 1:
 ====== PHP RFC: Deprecations for PHP 8.1 ====== ====== PHP RFC: Deprecations for PHP 8.1 ======
-  * Date: 2019-07-23+  * Date: 2021-02-23
   * Author: Nikita Popov <nikic@php.net>, George Peter Banyard <girgias@php.net>, Máté Kocsis <kocsismate@php.net>, Rowan Tommins <imsop@php.net>   * Author: Nikita Popov <nikic@php.net>, George Peter Banyard <girgias@php.net>, Máté Kocsis <kocsismate@php.net>, Rowan Tommins <imsop@php.net>
-  * Status: Under Discussion+  * Status: Implemented
  
 ===== Introduction ===== ===== Introduction =====
Line 16: Line 16:
   * ''FILE_BINARY'' and ''FILE_TEXT'' constants   * ''FILE_BINARY'' and ''FILE_TEXT'' constants
   * ''t'' fopen mode   * ''t'' fopen mode
-  * Passing bool for ''$amountOrUpOrDown'' argument of ''IntlCalendar::roll()''+  * Passing bool for ''$value'' argument of ''IntlCalendar::roll()''
   * Accessing static members on traits   * Accessing static members on traits
   * ''strptime()''   * ''strptime()''
Line 32: Line 32:
   * ''FILTER_SANITIZE_STRING''   * ''FILTER_SANITIZE_STRING''
   * ''oci8.old_oci_close_semantics'' ini setting   * ''oci8.old_oci_close_semantics'' ini setting
 +  * ''odbc_result_all()''
  
 ===== Proposal ===== ===== Proposal =====
  
 Each feature proposed for deprecation is voted separately and requires a 2/3 majority. All votes refer to deprecation in PHP 8.1 and removal in PHP 9.0. Each feature proposed for deprecation is voted separately and requires a 2/3 majority. All votes refer to deprecation in PHP 8.1 and removal in PHP 9.0.
 +
 +Voting started on 2021-06-30 and ends on 2021-07-14.
  
 ==== date_sunrise() and date_sunset() ==== ==== date_sunrise() and date_sunset() ====
Line 64: Line 67:
 The proposal is to deprecate ''date_sunset()'' and ''date_sunrise()'' in favor of ''date_sun_info()''. The ini settings ''date.default_latitude'', ''date.default_longitude'' and ''date.sunset_zenith'' are marked as deprecated in the documentation. In the next major version, both the functions and the ini settings will be removed. The proposal is to deprecate ''date_sunset()'' and ''date_sunrise()'' in favor of ''date_sun_info()''. The ini settings ''date.default_latitude'', ''date.default_longitude'' and ''date.sunset_zenith'' are marked as deprecated in the documentation. In the next major version, both the functions and the ini settings will be removed.
 This was initially discussed in: https://github.com/php/php-src/pull/4423. This was initially discussed in: https://github.com/php/php-src/pull/4423.
 +
 +<doodle title="Deprecate date_sunrise() and date_sunset()?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== key(), current(), next(), prev(), reset() on objects ==== ==== key(), current(), next(), prev(), reset() on objects ====
Line 74: Line 82:
  
 As such, the proposal is to deprecate key(), current(), next(), prev() and reset() on objects. The suggested replacement is to cast the object to array first, or call ''get_mangled_object_vars()'', depending on what the intention is. As such, the proposal is to deprecate key(), current(), next(), prev() and reset() on objects. The suggested replacement is to cast the object to array first, or call ''get_mangled_object_vars()'', depending on what the intention is.
 +
 +<doodle title="Deprecate key(), current(), next(), prev(), reset() on objects?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== mb_check_encoding() without argument ==== ==== mb_check_encoding() without argument ====
Line 98: Line 111:
  
 The proposal is to deprecate calling ''mb_check_encoding()'' without arguments. The proposal is to deprecate calling ''mb_check_encoding()'' without arguments.
 +
 +<doodle title="Deprecate mb_check_encoding() without argument?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== get_class(), get_parent_class() and get_called_class() without argument ==== ==== get_class(), get_parent_class() and get_called_class() without argument ====
Line 106: Line 124:
  
 As a caveat, if ''get_parent_class()'' is used to check whether the class has a parent, it is necessary to use ''get_parent_class(self::class)'' instead, because ''parent::class'' will generate an error if used inside a class without parent. As a caveat, if ''get_parent_class()'' is used to check whether the class has a parent, it is necessary to use ''get_parent_class(self::class)'' instead, because ''parent::class'' will generate an error if used inside a class without parent.
 +
 +<doodle title="Deprecate get_class(), get_parent_class() and get_called_class() without argument?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== FILE_BINARY and FILE_TEXT constants ==== ==== FILE_BINARY and FILE_TEXT constants ====
Line 114: Line 137:
  
 This was pointed out in: https://github.com/php/php-src/pull/5556 This was pointed out in: https://github.com/php/php-src/pull/5556
 +
 +<doodle title="Deprecate FILE_BINARY and FILE_TEXT constants?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== "t" fopen mode ==== ==== "t" fopen mode ====
Line 121: Line 149:
 > Again, for portability, it is also strongly recommended that you re-write code that uses or relies upon the 't' mode so that it uses the correct line endings and 'b' mode instead.  > Again, for portability, it is also strongly recommended that you re-write code that uses or relies upon the 't' mode so that it uses the correct line endings and 'b' mode instead. 
  
-The proposal is to deprecate the use of ''t'' mode in fopen(). Explicitly specifying the ''b'' mode remains supported.+The proposal is to deprecate the use of ''t'' mode in fopen() and other mode arguments. Explicitly specifying the ''b'' mode remains supported.
  
-There is a complication here: While ''fopen()'' itself defaults to binary mode, some other functions like ''proc_open()'' on pipe descriptors still default to text mode. It is not clear what should be done with these functions.+While ''fopen()'' defaults to binary mode, some other functions like ''proc_open()'' on pipe descriptors still default to text mode. Cases that use ''t'' as the default mode are excluded from this deprecation for the time being. We may include them in the future, which would require explicitly specifying ''b'' mode for them during a transitionary period.
  
-==== Passing bool for $amountOrUpOrDown argument of IntlCalendar::roll() ====+<doodle title="Deprecate t fopen mode?" auth="nikic" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle> 
 + 
 +==== Passing bool for $value argument of IntlCalendar::roll() ====
  
 <php>IntlCalendar::roll()</php> accepts an integer which specifies how much to add to a given field. The integer can be negative to subtract. <php>IntlCalendar::roll()</php> accepts an integer which specifies how much to add to a given field. The integer can be negative to subtract.
Line 132: Line 165:
  
 The proposal is to deprecate passing a boolean to this method argument. The proposal is to deprecate passing a boolean to this method argument.
 +
 +<doodle title="Deprecate passing bool for $value argument of IntlCalendar::roll()?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== Accessing static members on traits ==== ==== Accessing static members on traits ====
Line 144: Line 182:
     use T;     use T;
 } }
-var_dump(T::$foo); // Allowed.+var_dump(T::$foo); // Currently allowed.
 </PHP> </PHP>
  
-This is conceptually wrong, and causes various complications. For example, the meaning of ''self'' is ill-defined (which normally refers to the using class, not the trait)the behavior of static variables in methods may change depending on whether trait method has been called prior to being usedand opcache preloading requires constant initializers in traits to be fully resolved (as they may be used directly).+This is conceptually wrong, and causes various complications. For example, the meaning of ''self'' is ill-defined -- normally, it refers to the using class, not the trait, but there is no "using class" in this context. Static member access on traits is regular complication for new functionality, because it results in an impure behavior model. For example, opcache preloading had to require evaluated initializers in traits, because there is a possibility that that members are accessed directly, even though in ordinary usage they can only be accessed after being imported into some class.
  
-There is a somewhat dated analysis of projects using this "feature" at https://github.com/php/php-src/pull/4829#issuecomment-542224541.+There is a somewhat dated analysis of projects using this functionality at https://github.com/php/php-src/pull/4829#issuecomment-542224541.
  
 The proposal is to deprecate the ability to access static properties and static methods directly on traits. The proposal is to deprecate the ability to access static properties and static methods directly on traits.
 +
 +<doodle title="Deprecate accessing static members on traits?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== strptime() ==== ==== strptime() ====
Line 159: Line 202:
 > Internally, this function calls the strptime() function provided by the system's C library. This function can exhibit noticeably different behaviour across different operating systems. The use of date_parse_from_format(), which does not suffer from these issues, is recommended on PHP 5.3.0 and later. > Internally, this function calls the strptime() function provided by the system's C library. This function can exhibit noticeably different behaviour across different operating systems. The use of date_parse_from_format(), which does not suffer from these issues, is recommended on PHP 5.3.0 and later.
  
-Notably, distributions like alpine that use musl instead of glibc may exhibit unexpected behavior.+Notably, distributions like alpine that use musl instead of glibc may exhibit unexpected behavior. Additionally, ''strptime()'' is locale-based, and as such may be affected by code running in a different thread.
  
 As the note already mentioned, ''date_parse_from_format()'' is an alternative that is always available and always behaves consistently. ''DateTime::createFromFormat()'' is another alternative that creates a ''DateTime'' object instead. ''IntlDateFormatter::parse()'' is available as a more sophisticated, localization-aware alternative. As the note already mentioned, ''date_parse_from_format()'' is an alternative that is always available and always behaves consistently. ''DateTime::createFromFormat()'' is another alternative that creates a ''DateTime'' object instead. ''IntlDateFormatter::parse()'' is available as a more sophisticated, localization-aware alternative.
  
 The proposal is to deprecate the ''strptime()'' function in favor of portable alternatives. The proposal is to deprecate the ''strptime()'' function in favor of portable alternatives.
 +
 +<doodle title="Deprecate strptime()?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== strftime() and gmstrftime() ==== ==== strftime() and gmstrftime() ====
  
-The ''strftime()'' and ''gmstrftime()'' functions exhibit similar issues as ''strptime()'', in that the formats they support, as well as their behavior, is platform-dependent. Unlike ''strptime()'', these functions are available on Windows, though with a different feature set than on Linux. Musl-based distributions like Alpine do not support timezone-related format specifiers correctly.+The ''strftime()'' and ''gmstrftime()'' functions exhibit similar issues as ''strptime()'', in that the formats they support, as well as their behavior, is platform-dependent. Unlike ''strptime()'', these functions are available on Windows, though with a different feature set than on Linux. Musl-based distributions like Alpine do not support timezone-related format specifiers correctly. These functions are also locale-based, and as such may exhibit thread-safety issues.
  
-Once again ''DateTime::format()'' provides a portable alternative, and ''IntlDateFormatter::format()'' provides a more sophisticated, localization-aware alternative.+Once again ''date()'' or ''DateTime::format()'' provide portable alternatives, and ''IntlDateFormatter::format()'' provides a more sophisticated, localization-aware alternative.
  
 The proposal is to deprecate ''strftime()'' and ''gmstrftime()'' in favor of these alternatives. The proposal is to deprecate ''strftime()'' and ''gmstrftime()'' in favor of these alternatives.
 +
 +<doodle title="Deprecate strftime() and gmstrftime()?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== mhash*() function family ==== ==== mhash*() function family ====
Line 178: Line 231:
  
 The proposal is to deprecate ''mhash()'', ''mhash_keygen_s2k()'', ''mhash_count()'', ''mhash_get_block_size()'' and ''mhash_get_hash_name()'' in favor of the standard ext/hash functionality. The proposal is to deprecate ''mhash()'', ''mhash_keygen_s2k()'', ''mhash_count()'', ''mhash_get_block_size()'' and ''mhash_get_hash_name()'' in favor of the standard ext/hash functionality.
 +
 +<doodle title="Deprecate mhash*() family of functions?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== ctype_*() function family accepts int parameters ==== ==== ctype_*() function family accepts int parameters ====
Line 192: Line 250:
  
 The proposal is to deprecate passing of non-strings to ''ctype_*()'' functions. In the next major versions, ''ctype_*()'' will be changed to accept a string parameter under standard semantics. The proposal is to deprecate passing of non-strings to ''ctype_*()'' functions. In the next major versions, ''ctype_*()'' will be changed to accept a string parameter under standard semantics.
 +
 +<doodle title="Deprecate int parameters to ctype_*() functions?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== Return by reference with void type ==== ==== Return by reference with void type ====
Line 204: Line 267:
  
 The proposal is to throw a compile-time deprecation for function signatures using by-reference returns in conjunction with void. The proposal is to throw a compile-time deprecation for function signatures using by-reference returns in conjunction with void.
 +
 +<doodle title="Deprecate return by reference with void type?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== NIL constant defined by the IMAP extension ==== ==== NIL constant defined by the IMAP extension ====
  
-The ''NIL'' constant corresponds to the value ''0'', and can be confused with ''null''.+The ''NIL'' constant corresponds to the value ''0'', and can be confused with ''null''. It is an ideosyncracy of the IMAP C API.
  
 The proposal is to deprecate this constant. The proposal is to deprecate this constant.
 +
 +<doodle title="Deprecate NIL constant defined by the IMAP extension?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== Calling overloaded pgsql functions without the connection argument ==== ==== Calling overloaded pgsql functions without the connection argument ====
Line 231: Line 304:
  
 The proposal is to deprecate any use of the "default connection" in ext/pgsql. A deprecation notice will be thrown if a pgsql function is called without explicitly specifying the connection. The proposal is to deprecate any use of the "default connection" in ext/pgsql. A deprecation notice will be thrown if a pgsql function is called without explicitly specifying the connection.
 +
 +<doodle title="Deprecate calling overloaded pgsql functions without the connection argument?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== $num_points parameter of image(open|filled)polygon ==== ==== $num_points parameter of image(open|filled)polygon ====
Line 251: Line 329:
 imagepolygon($im, array_slice($points, 0, 6), 0x000000); // after imagepolygon($im, array_slice($points, 0, 6), 0x000000); // after
 </PHP> </PHP>
 +
 +<doodle title="Deprecate $num_points parameter of image(open|filled)polygon?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== mysqli::init() ==== ==== mysqli::init() ====
Line 264: Line 347:
     public function __construct($host, $user, $passwd, $db, $port, $socket) {     public function __construct($host, $user, $passwd, $db, $port, $socket) {
         // parent::init();         // parent::init();
-        // change to:+        // replace the above line with the following line:
         parent::__construct();         parent::__construct();
 +        
         parent::real_connect($host, $user, $passwd, $db, $port, $socket);         parent::real_connect($host, $user, $passwd, $db, $port, $socket);
     }     }
 } }
 </PHP> </PHP>
 +
 +<doodle title="Deprecate mysqli::init()?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== filter.default ini setting ==== ==== filter.default ini setting ====
Line 282: Line 371:
  
 The proposal is to emit a deprecation warning if ''filter.default'' is set to a value other than ''unsafe_raw'' (the default). No separate deprecation warning is emitted for ''filter.default_options'', but both ini settings will be removed together in the next major version. The proposal is to emit a deprecation warning if ''filter.default'' is set to a value other than ''unsafe_raw'' (the default). No separate deprecation warning is emitted for ''filter.default_options'', but both ini settings will be removed together in the next major version.
 +
 +<doodle title="Deprecate filter.default ini setting?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== auto_detect_line_endings ini setting ==== ==== auto_detect_line_endings ini setting ====
Line 289: Line 383:
 The proposal is to emit a deprecation warning if ''auto_detect_line_endings'' is enabled. The proposal is to emit a deprecation warning if ''auto_detect_line_endings'' is enabled.
  
-==== 'ssl_methodoption to SoapClient constructor ====+<doodle title="Deprecate auto_detect_line_endings ini setting?" auth="nikic" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle> 
 + 
 +==== ssl_method option to SoapClient constructor ====
  
 One of the many options which can be passed (in an associative array) to the ''SoapClient'' constructor is ''ssl_method'', which theoretically allows selection of the SSL/TLS version. The value is one of four extension-specific constants: One of the many options which can be passed (in an associative array) to the ''SoapClient'' constructor is ''ssl_method'', which theoretically allows selection of the SSL/TLS version. The value is one of four extension-specific constants:
Line 299: Line 398:
 A full set of options (including both SSL 3 and all individual versions of TLS) is available using the ''['ssl' => ['crypto_method' => ...]'' option to ''stream_context_create'', which can then be passed to the ''SoapClient'' in the ''context'' parameter. A full set of options (including both SSL 3 and all individual versions of TLS) is available using the ''['ssl' => ['crypto_method' => ...]'' option to ''stream_context_create'', which can then be passed to the ''SoapClient'' in the ''context'' parameter.
  
-The proposal is to deprecate passing an ''ssl_method'' option to the constructor, and recommend use of ''context'' option instead.+The proposal is to deprecate passing an ''ssl_method'' option to the constructor, and recommend the use of ''context'' option instead. 
 + 
 +<doodle title="Deprecate ssl_method option to SoapClient constructor?" auth="nikic" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle>
  
 ==== FILTER_SANITIZE_STRING ==== ==== FILTER_SANITIZE_STRING ====
Line 305: Line 409:
 This is a very dubious filter that has almost no use. It removes NUL bytes, encodes single and double quotes in HTML, and removes anything between ''<'' and optional ''>''. It does not function the same as ''strip_tags()'' as pointed out in this comment https://www.php.net/manual/en/filter.filters.sanitize.php#118186 This is a very dubious filter that has almost no use. It removes NUL bytes, encodes single and double quotes in HTML, and removes anything between ''<'' and optional ''>''. It does not function the same as ''strip_tags()'' as pointed out in this comment https://www.php.net/manual/en/filter.filters.sanitize.php#118186
  
 +This filter is dangerously misleading and encourages bad practice, in that the set of encoded/stripped characters is not suitable for any particular purpose. It seems to be intended as a kind of generic string filter that renders the string safe in a magic fashion, without taking into account the context where it will be used. Use of this filter should be replaced with escaping/encoding specific to the given context.
  
-It is also one of the only two filters using ''FILTER_FLAG_NO_ENCODE_QUOTES'' flag+The name of the filter can also be confused with a default filter for accepting arbitrary strings (which would be more in line with what other filters like FILTER_SANITIZE_INT do). The filter that actually does this is FILTER_UNSAFE_RAW, which sounds like something one should not use. In reality, it is the use of FILTER_SANITIZE_STRING which will result in data corruption.
  
-This filter is very misleading especially to new users who are looking for a default string filter. The real default one is called FILTER_UNSAFE_RAW which sounds like something one should not use. While in reality, it is FILTER_SANITIZE_STRING that can damage your data and should not be used+The proposal is to deprecate the ''FILTER_SANITIZE_STRING'' constant, its alias ''FILTER_SANITIZE_STRIPPED'', as well as use of this filter.
  
-This also includes the deprecation of FILTER_SANITIZE_STRIPPED which is just its alias. +<doodle title="Deprecate FILTER_SANITIZE_STRING?" auth="nikic" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle>
  
 ==== oci8.old_oci_close_semantics INI setting ==== ==== oci8.old_oci_close_semantics INI setting ====
Line 316: Line 424:
 By enabling this INI setting, ''oci_close()'' will do nothing instead of closing the connection. As it only exists for backward compatibility purposes for a long time, we should remove it. By enabling this INI setting, ''oci_close()'' will do nothing instead of closing the connection. As it only exists for backward compatibility purposes for a long time, we should remove it.
  
-===== Backward Incompatible Changes =====+The proposal is to throw a deprecation warning if ''oci8.old_oci_close_semantics'' is enabled.
  
-For PHP 8.1 additional deprecation notices will appear. For PHP 9.0 the previously deprecated functionality will no longer be available.+<doodle title="Deprecate oci8.old_oci_close_semantics INI setting?" auth="nikic" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle>
  
-===== Removed from this proposal =====+==== odbc_result_all() ====
  
-The following entries were originally added to this proposal and then dropped.+The [[https://www.php.net/odbc_result_all|odbc_result_all()]] function prints all rows from an ODBC query result as an HTML table. However, the printed data is not escaped. This means that the function is not only of very dubious usefulness, but also actively dangerous when used for non-debugging purposes.
  
-==== DateTimeInterface::ISO8601 ====+The proposal is to deprecate the ''odbc_result_all()'' function.
  
-The documentation says:+<doodle title="Deprecate odbc_result_all()?" auth="nikic" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle>
  
-> Note: This format is not compatible with ISO-8601, but is left this way for backward compatibility reasons. Use DateTime::ATOM or DATE_ATOM for compatibility with ISO-8601 instead. +===== Backward Incompatible Changes =====
  
-There's a number of bug reports related to thisFrom what I understand, the core problem here is not that the ISO8601 format is //wrong//, it's just one of multiple legal ISO-8601 formatsAs DateTime formats always refer to a specific format, not a set of multiple possible ones, there doesn't seem to be anything actionable here.+For PHP 8.1 additional deprecation notices will appear. For PHP 9.0 the previously deprecated functionality will no longer be available. 
 + 
 +===== Removed from this proposal ===== 
 + 
 +The following entries were originally added to this proposal and then dropped.
  
 ==== get_browser() function ==== ==== get_browser() function ====
Line 378: Line 496:
 $f = fopen($url, 'r', context: $context); $f = fopen($url, 'r', context: $context);
 $response = stream_get_contents($f); $response = stream_get_contents($f);
-$headers = stream_get_meta_data($fp)['wrapper_data'];+$headers = stream_get_meta_data($f)['wrapper_data'];
 </PHP> </PHP>
  
rfc/deprecations_php_8_1.txt · Last modified: 2021/07/14 07:23 by nikic