rfc:deprecations_php_8_0

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
rfc:deprecations_php_8_0 [2021/01/15 05:22] – Add unserialize_callback_func INI setting to the list girgiasrfc:deprecations_php_8_0 [2021/02/23 14:37] (current) nikic
Line 1: Line 1:
-====== PHP RFC: Deprecations for PHP 8.======+====== PHP RFC: Deprecations for PHP 8.======
   * Date: 2019-07-23   * Date: 2019-07-23
   * Author: Nikita Popov <nikic@php.net>, George Peter Banyard <girgias@php.net>, Máté Kocsis <kocsismate@php.net>   * Author: Nikita Popov <nikic@php.net>, George Peter Banyard <girgias@php.net>, Máté Kocsis <kocsismate@php.net>
   * Status: Under Discussion   * Status: Under Discussion
  
-===== Introduction ===== +**This RFC was postponed to PHP 8.1, see [[rfc:deprecations_php_8_1|Deprecations for PHP 8.1]].**
- +
-The RFC proposes to deprecate the listed functionality in PHP 8.1 and remove it in PHP 9. +
- +
-The following list provides a short overview of the functionality targeted for deprecation, while more detailed explanation is provided in the Proposal section: +
- +
-  ''date_sunrise()'' and ''date_sunset()'' +
-  ''key()'', ''current()'', ''next()'', ''prev()'', and ''reset()'' on objects +
-  * ''mb_check_encoding()'' without argument +
-  * ''get_class()'', ''get_parent_class()'' and ''get_called_class()'' without argument +
-  * ''FILE_BINARY'' and ''FILE_TEXT'' constants +
-  * ''t'' fopen mode +
-  * Passing bool for ''$amountOrUpOrDown'' argument of ''IntlCalendar::roll()'' +
-  * Accessing static members on traits +
-  * ''strftime()'' and ''gmtstrftime()'' +
-  * Passing a method name as the first parameter to ''ReflectionMethod'''s constructor +
-  * ''mhash*()'' function family +
-  * %%''DatePeriod::__construct()''%% +
-  * ''ctype_*()'' function family accepts ''int'' parameters +
-  * Return by reference with void type +
-  * NIL constant defined by the IMAP extension +
-  * ''unserialize_callback_func'' INI setting +
- +
-===== 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. +
- +
-==== date_sunrise() and date_sunset() ==== +
- +
-These two functions have the signature: +
- +
-<PHP> +
-function date_sunset( +
-    int $timestamp, +
-    int $format = SUNFUNCS_RET_STRING, +
-    float $latitude = ini_get("date.default_latitude"), +
-    float $longitude = ini_get("date.default_longitude"), +
-    float $zenith = ini_get("date.sunset_zenith"), +
-    float $gmt_offset = 0 +
-): mixed; +
-</PHP> +
- +
-This function depends on ini settings that specify the "default" latitude and longitude, a concept that makes very little sense. Additionally it requires familiarity with appropriate zenith values to use for different purposes. +
- +
-''date_sunset()'' and ''date_sunrise()'' have since been superseded by ''date_sun_info()'': +
- +
-<PHP> +
-function date_sun_info(int $time, float $latitude, float $longitude): array; +
-</PHP> +
- +
-This function does not use "default" latitude and longitude, and returns an associative array of multiple different definitions of the sunrise/sunset concept. +
- +
-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. +
- +
-==== key(), current(), next(), prev(), reset() on objects ==== +
- +
-The ''key()'' family of functions, which are used to manipulate the internal array pointer, also accept objects. In this case they work on the mangled property table. That is, using ''key()'' and friends on an object is essentially the same as using them on ''get_mangled_object_vars($object)''+
- +
-This catches many people off guard, because they expect ''key()'' etc. to integrate with the iterator interface. That is, if the passed object implements ''Iterator'' then ''key($object)'' should perform an ''$object->key()'' call. The water here have been further muddied by ''ArrayObject'', which prior to PHP 7.4 was the only object where ''key()'' etc. //did// effectively integrate with the iterator interface. +
- +
-There are principally two ways to resolve this: The first is to deprecate the use of ''key()'' etc on objects, and instead require people to perform an explicit ''(array)'' cast or ''get_mangled_object_vars()'' call beforehand. The other is to actually make these functions integrate with iterators. The issue I see with the latter is that we would only be able to support the ''Iterator'' interface proper, but not general ''Traversable''s: For these ''IteratorAggregate::getIterator()'', or the internal ''get_iterator()'' handler need to be called once at the start, which is not possible through the array iteration interface, as it consists of multiple independent functions. Additionally, the ''prev()'' function cannot be implemented for iterators. +
- +
-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. +
- +
-==== mb_check_encoding() without argument ==== +
- +
-The ''mb_check_encoding()'' usually accepts a string and an encoding, but can also be called without arguments. The documentation says: +
- +
-> If it is omitted, this function checks all the input from the beginning of the request.  +
- +
-The implementation says: +
- +
-<code> +
-/* FIXME: Actually check all inputs, except $_FILES file content. */ +
-if (MBSTRG(illegalchars) == 0) { +
-    RETURN_TRUE; +
-+
-RETURN_FALSE; +
-</code> +
- +
-This %%FIXME%% does not induce a sense of confidence in this function... +
- +
-Further research shows that the documentation is correct, in that //any// encoding checking or conversion functionality invoked during a request will increment ''MBSTRG(illegalchars)''. As such, ''mb_check_encoding()'' tells you whether any illegal encoding has been encountered at any point. My best guess is that this was intended to be used in conjunction with the ''encoding_translation'' feature, which "treats" incoming SAPI data. +
- +
-Overall this functionality is confusing, and the implementation is unfinished or broken. There are no calls to ''mb_check_encoding()'' without argument in popular composer packages. +
- +
-The proposal is to deprecate calling ''mb_check_encoding()'' without arguments. +
- +
-==== get_class(), get_parent_class() and get_called_class() without argument ==== +
- +
-In PHP 7.2, [[rfc:get_class_disallow_null_parameter|passing null to ''get_class()'']] was forbidden, because this behavior was very bug prone. However, the ability to call ''get_class()'' without argument was retained. In that case ''get_class()'' is approximately the same as ''self::class''. ''get_parent_class()'' exhibits the same behavior. +
- +
-The proposal is to deprecate argument-less ''get_class()'', ''get_parent_class()'' and ''get_called_class()'' in favor of the dedicated ''self::class'', ''parent::class'' and ''static::class'' syntax, which was introduced in PHP 5.5. (''get_called_class()'' only has an argument-less form, so it would be deprecated entirely.) +
- +
-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. +
- +
-==== FILE_BINARY and FILE_TEXT constants ==== +
- +
-These were introduced in PHP 5.2.7 for forward compatibility with PHP 6, but don't have any effect. These constants are especially confusing because ''fopen()'' supports ''b'' (binary) and ''t'' (text) modes, which //do// have an effect, but a completely unrelated one. +
- +
-The proposal is to deprecate the ''FILE_BINARY'' and ''FILE_TEXT'' constants. +
- +
-This was pointed out in: https://github.com/php/php-src/pull/5556 +
- +
-==== "t" fopen mode ==== +
- +
-Next to the standard modes, fopen also accepts ''t'' and ''b'' modes, which are only meaningful on Windows. When ''b'' is used (which is the default), the file is treated as usual. If ''t'' is specified, automatic conversion between LF and CRLF line endings is performed. The documentation says: +
- +
-> 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. +
- +
-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. The default for these functions should be swapped for PHP 8, independently of this deprecation proposal. +
- +
-==== Passing bool for $amountOrUpOrDown 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. +
- +
-However, it also accepts a boolean argument, in which case ''true'' is interpreted as ''1'' and ''false'' is interpreted as ''-1''This does not appear to be actually useful for anything, makes for a confusing function signature, and violates PHP's usual type coercion rules. +
- +
-The proposal is to deprecate passing a boolean to this method argument. +
- +
-==== Accessing static members on traits ==== +
- +
-Currently, it is possible to directly access static trait members, rather than accessing them on the class using the trait: +
- +
-<PHP> +
-trait T { +
-    public static $foo; +
-+
-class C { +
-    use T; +
-+
-var_dump(T::$foo); // Allowed. +
-</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 a trait method has been called prior to being used, and opcache preloading requires constant initializers in traits to be fully resolved (as they may be used directly). +
- +
-There is a somewhat dated analysis of projects using this "feature" 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. +
- +
-==== strftime() and gmstrftime() ==== +
- +
-==== strptime() ==== +
- +
-==== Passing a method name as the first parameter to ReflectionMethod::__construct() ==== +
- +
-A ''ReflectionMethod::fromMethodName()'' method should be added as a replacement. +
- +
-==== mhash*() function family ==== +
- +
-''mhash*()'' functions were integrated into ext/hash in PHP 5.3 as a compatibility layer for ext/mhash (which has been removed in PHP 7.0), but they are hardly ever used, and very ill-behaved (primarily ''mhash()''). +
- +
-==== DatePeriod::__construct() ==== +
- +
-This is a heavily overloaded function (it has 3 signatures) which should be deprecated in favour of 3 factory methods. +
- +
-==== ctype_*() function family accepts int parameters ==== +
- +
-Although the documentation currently lists ''string'' as a valid parameter type for ''ctype_*'' functions, it's not the case. They also accept an integer which is only mentioned in a note: +
- +
-<blockquote> +
-If an integer between -128 and 255 inclusive is provided, it is interpreted as the ASCII value of a single character (negative values have 256 added in order to allow characters in the Extended ASCII range). Any other integer is interpreted as a string containing the decimal digits of the integer. +
-</blockquote> +
- +
-Moreover, if any other type than int or string is passed, ''ctype_*()'' functions silently return ''false''+
- +
-Since the current behaviour is highly surprising, passing integer values to ''ctype_*()'' functions should be deprecated first, and ZPP should be modified to only accept strings in the next major version. +
- +
-==== Predefined variable $http_response_header ==== +
-W.I.P. +
-See https://www.php.net/manual/en/reserved.variables.httpresponseheader.php +
-We already deprecated/removed $php_errormsg and $HTTP_RAW_POST_DATA +
- +
-==== Return by reference with void type ==== +
- +
-''function &test(): void {}'' currently allows, probably shouldn't be? +
- +
- +
-==== NIL constant defined by the IMAP extension ==== +
-The ''NIL'' constant corresponds to the value ''0'', and can be confused with ''null''+
- +
-==== unserialize_callback_func INI setting ==== +
-W.I.P. (but from my understanding this was used with __autoload() only - girgias) +
- +
-===== Backward Incompatible Changes ===== +
- +
-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. +
- +
-==== 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 ==== +
- +
-This was originally included on the rationale that ''get_browser()'' is much slower than userland browscap implementations. However, this is no longer the case since a PHP 7.0 patch release, see https://github.com/php/php-src/pull/2242.+
rfc/deprecations_php_8_0.txt · Last modified: 2021/02/23 14:37 by nikic