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/06/15 10:47]
nikic
rfc:deprecations_php_8_1 [2021/07/14 07:23] (current)
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 37: Line 37:
  
 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 65: 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 75: 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 99: 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 107: 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 115: 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 122: 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 133: 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 153: Line 190:
  
 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 160: 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 179: 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 193: 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 205: 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 232: 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 252: 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 265: 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 283: 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 290: 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 300: 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 308: Line 411:
 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. 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.
  
-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 use of FILTER_SANITIZE_STRING which will result in data corruption.+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.
  
 The proposal is to deprecate the ''FILTER_SANITIZE_STRING'' constant, its alias ''FILTER_SANITIZE_STRIPPED'', as well as use of this filter. The proposal is to deprecate the ''FILTER_SANITIZE_STRING'' constant, its alias ''FILTER_SANITIZE_STRIPPED'', as well as use of this filter.
 +
 +<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 317: Line 425:
  
 The proposal is to throw a deprecation warning if ''oci8.old_oci_close_semantics'' is enabled. The proposal is to throw a deprecation warning if ''oci8.old_oci_close_semantics'' is enabled.
 +
 +<doodle title="Deprecate oci8.old_oci_close_semantics INI setting?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ==== odbc_result_all() ==== ==== odbc_result_all() ====
Line 323: Line 436:
  
 The proposal is to deprecate the ''odbc_result_all()'' function. The proposal is to deprecate the ''odbc_result_all()'' function.
 +
 +<doodle title="Deprecate odbc_result_all()?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
Line 331: Line 449:
  
 The following entries were originally added to this proposal and then dropped. The following entries were originally added to this proposal and then dropped.
- 
-==== DateTimeInterface::ISO8601 ==== 
- 
-The documentation says: 
- 
-> 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.  
- 
-There's a number of bug reports related to this. From what I understand, the core problem here is not that the ISO8601 format is //wrong//, it's just one of multiple legal ISO-8601 formats. As DateTime formats always refer to a specific format, not a set of multiple possible ones, there doesn't seem to be anything actionable here. 
  
 ==== get_browser() function ==== ==== get_browser() function ====
Line 386: 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.1623754059.txt.gz · Last modified: 2021/06/15 10:47 by nikic