PHP: rfc:deprecations_php_8_4

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: Deprecations for PHP 8.4 ======
  * Date: 2023-07-25
  * Authors:
    * Niels Dossche <nielsdos@php.net>
    * Gina Peter Banyard <girgias@php.net>
    * Máté Kocsis <kocsismate@php.net>
    * Tim Düsterhus <timwolla@php.net>
    * Kamil Tekiela <dharman@php.net>
    * Jorg Sowa <jorg.sowa@gmail.com>
  * Status: Pending Implementation
  * Implementation: TBD
    * [[https://github.com/php/php-src/commit/587110c5bf44362fa81606c492c9a668b2160d9a|Formally deprecate Soft-deprecated DOMDocument and DOMEntity properties]]
    * [[https://github.com/php/php-src/commit/d9eb3783bdd6947a635f132f8c240de8f40e8704|Remove DOMImplementation::getFeature($feature, $version)]]
    * [[https://github.com/php/php-src/commit/0aec0faa275df28597cd0cc82e64f7072b8e2c0f|Deprecate DOM_PHP_ERR Constant]]
    * [[https://github.com/php/php-src/commit/ecd11b968713025bba6fc145a0765f85f48a8a00|unserialize()'s 'S' tag]]
    * [[https://github.com/php/php-src/commit/e8ff7c70f9669f1a54c47c018ccc0f80bc0c929b|session.sid_length and session.sid_bits_per_character]]
    * [[https://github.com/php/php-src/commit/43def0af4629b29654798f7dec3daf2dfddf039f|Deprecate SplFixedArray::__wakeup()]]
    * [[https://github.com/php/php-src/commit/25b4696530c5dfad6b04a57c274200beec51ab0d|xml_set_object() and xml_set_*_handler() with string method names]]
    * [[https://github.com/php/php-src/commit/bb2836eced81cdf7aeeddafb20c487cea0b5dfc8|Passing null and false to dba_key_split()]]
    * [[https://github.com/php/php-src/pull/15236|Deprecate passing incorrect data types for options to ext/hash functions]]
    * [[https://github.com/php/php-src/commit/b9fef523c14d77af038160df4d0150807d3fca53|Constants SUNFUNCS_RET_STRING, SUNFUNCS_RET_DOUBLE, SUNFUNCS_RET_TIMESTAMP]]
    * [[https://github.com/php/php-src/commit/c818d944cf998b3151e4b312d655c51223612c4e|Deprecate proprietary CSV escaping mechanism]]
    * [[https://github.com/php/php-src/commit/d313ad6098430f4e61f0121a9e7ab392d195e4e4|Deprecate E_STRICT Constant]]
    * Deprecate returning non-string values from a user output handler
    * Deprecate producing output in a user output handler
    * [[https://github.com/php/php-src/commit/cbcad9fdaf816e4512cecfb6c1d50fcc0ea7294d|Deprecate mysqli_ping() and mysqli::ping()]]
    * [[https://github.com/php/php-src/commit/42336e135962f80924c83746d36d6f04949a0cea|Deprecate mysqli_refresh()]]
    * [[https://github.com/php/php-src/commit/7801f40449ba3b46d4cf6d5b8417b7c274c25f95|Deprecate mysqli_kill()]]
    * [[https://github.com/php/php-src/commit/4f58d5b0df823dbdc4e629d98b3d564050e9173e|Deprecate the second parameter to mysqli_store_result()]]
    * [[https://github.com/php/php-src/commit/f5f92941537993d871888608dae224d1c0474786|Deprecate lcg_value()]]
    * [[https://github.com/php/php-src/commit/1e3d918936d715466475434e7a4d7db2f36afa10|Deprecate passing E_USER_ERROR to trigger_error()]]
    * [[https://github.com/php/php-src/commit/0a23b0678da5534e33d3482c0b13924f7e924ab5|Deprecate using a single underscore ''_'' as a class name]]
    * [[https://github.com/php/php-src/commit/42497c1ea56a8452af84ea9c2177c1175f4136d6|Deprecate SOAP_FUNCTIONS_ALL constant and passing it to SoapServer::addFunction()]]

===== Introduction =====

The RFC proposes to deprecate the listed functionality in PHP 8.4 and remove it in PHP 9 (except where otherwise noted).

The following list provides a short overview of the functionality targeted for deprecation, while more detailed explanation is provided in the Proposal section:

  * Formally deprecate Soft-deprecated <php>DOMDocument</php> and <php>DOMEntity</php> properties
  * Remove <php>DOMImplementation::getFeature($feature, $version)</php>
  * Deprecate <php>DOM_PHP_ERR</php> Constant
  * <php>unserialize()</php>'s 'S' tag
  * ''session.sid_length'' and ''session.sid_bits_per_character''
  * Deprecate <php>SplFixedArray::__wakeup()</php>
  * <php>xml_set_object()</php> and <php>xml_set_*_handler()</php> with string method names
  * Passing <php>null</php> and <php>false</php> to <php>dba_key_split()</php>
  * Deprecate passing incorrect data types for options to ext/hash functions
  * Constants <php>SUNFUNCS_RET_STRING</php>, <php>SUNFUNCS_RET_DOUBLE</php>, <php>SUNFUNCS_RET_TIMESTAMP</php>
  * Deprecate proprietary CSV escaping mechanism
  * Deprecate <php>E_STRICT</php> Constant
  * Deprecate <php>strtok()</php>
  * Deprecate returning non-string values from a user output handler
  * Deprecate producing output in a user output handler
  * <php>file_put_contents()</php> with <php>$data</php> as an array
  * Deprecate <php>mysqli_ping()</php> and <php>mysqli::ping()</php>
  * Deprecate <php>mysqli_refresh()</php>
  * Deprecate <php>mysqli_kill()</php>
  * Deprecate the second parameter to <php>mysqli_store_result()</php>
  * Deprecate <php>lcg_value()</php>
  * Deprecate <php>uniqid()</php>
  * Deprecate <php>md5()</php>, <php>sha1()</php>, <php>md5_file()</php>, and <php>sha1_file()</php>
  * Deprecate passing <php>E_USER_ERROR</php> to <php>trigger_error()</php>
  * Deprecate using a single underscore ''_'' as a class name
  * Deprecate <php>SOAP_FUNCTIONS_ALL</php> constant and passing it to <php>SoapServer::addFunction()</php>

===== Proposal =====

Each feature proposed for deprecation is voted separately and requires a 2/3 majority. All votes refer to deprecation in PHP 8.4 and removal in PHP 9 (except where otherwise noted).

==== Formally deprecate Soft-deprecated DOMDocument and DOMEntity properties ====

  * Author: Máté Kocsis <kocsismate@php.net>
  * Implementation: https://github.com/php/php-src/pull/15369

The following properties have been soft-deprecated for at least [[https://github.com/php/doc-en/commit/7fde5c7d758f8c2809fec99ce36b05043847224a|17 years]]:

  * <php>DOMDocument::$actualEncoding</php>: it is just an alias to <php>DOMDocument::$encoding</php>
  * <php>DOMDocument::$config</php>: it has always returned null
  * <php>DOMEntity::$actualEncoding</php>: it has always returned null
  * <php>DOMEntity::$encoding</php>: it has always returned null
  * <php>DOMEntity::$version</php>: it has always returned null

As such we propose to formally deprecate them.

<doodle title="Formally deprecate and remove the aforementioned DOMDocument and DOMEntity properties?" auth="kocsismate" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Remove DOMImplementation::getFeature($feature, $version) ====

  * Author: Niels Dossche <nielsdos@php.net>
  * Implementation: https://github.com/php/php-src/commit/d9eb3783bdd6947a635f132f8c240de8f40e8704

<php>DOMImplementation::getFeature($feature, $version)</php> used to be a feature of DOM Core Level 3 https://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030226/DOM3-Core.html#core-DOMImplementation3-getFeature, but it was never implemented in PHP, i.e. it always threw a "not implemented" exception. It was also never documented because of this. Furthermore, the feature has been removed from the current living DOM spec. It doesn't make sense to keep a feature alive that has never been implemented and is removed by the reference specification.

As such, we propose to directly remove the function as a deprecation wouldn't make much sense here.

<doodle title="Remove DOMImplementation::getFeature($feature, $version)" auth="nielsdos" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Deprecate DOM_PHP_ERR Constant ====

  * Author: Niels Dossche <nielsdos@php.net>
  * Implementation: https://github.com/php/php-src/commit/0aec0faa275df28597cd0cc82e64f7072b8e2c0f

PR https://github.com/php/php-src/pull/11927 got rid of the last use of <php>DOM_PHP_ERR</php> in PHP.
It is a non-standard and non-well-defined error code. The last use was for an out-of-memory situation but that's inconsistent as we normally use <php>INVALID_STATE_ERR</php> for that.

GitHub search reveals [[https://github.com/search?q=DOM_PHP_ERR+language%3APHP&type=code&l=PHP|174 matches]] (as of Jan 20 2024) for <php>DOM_PHP_ERR</php>. There are occurrences in string-form, i.e. <php>"DOM_PHP_ERR"</php> that normally doesn't get affected, some in code quality/compatibility tools, and some in php-src fork's stub files.

The remaining actual use is in Symfony's DOMCaster in an array that maps a constant back to its actual name. They can fix the deprecation by replacing the constant with its value until versions older than PHP 8.4 no longer need to be supported by the library.
There don't seem to be any other actual users of this.

<doodle title="Deprecate DOM_PHP_ERR constant?" auth="nielsdos" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== unserialize()'s 'S' tag ====

  * Author: Tim Düsterhus <timwolla@php.net>
  * Implementation: https://github.com/php/php-src/pull/12309

Strings serialized with PHP's native serialization mechanism are represented with the (lowercase) ''s'' tag, followed by the length of the string and the raw binary representation of the string contents. During the development of the never-released PHP 6, the serialization format of binary strings [[https://github.com/php/php-src/commit/1f2d5e3b00d19bd6d0db40d7fc2badaa2d65082e|was changed]] to use an escaped representation for non-ASCII characters, likely to make the serialization output compatible with PHP 6's Unicode strings where not all byte sequences are valid. This escaped format was then represented with the uppercase ''S'' tag [[https://github.com/php/php-src/commit/7ccba6624df074051f24efabd5d88d9c0d2a8ec0|in a follow-up commit]] and support for that uppercase ''S'' tag [[https://github.com/php/php-src/commit/8f5310afad0eeef6f2e45a03f6ff7d4a2a7653ce|added to PHP 5]] in an attempt to provide interoperability with serialized binary strings between PHP 5 and PHP 6. This support for the uppercase ''S'' tag remains in PHP until today.

PHP's native serializer is a security-sensitive part of the standard library, the simpler the logic the smaller the chance for security issues and the easier it is to verify the code for correctness. There are no tests verifying the functionality of the uppercase ''S'' tag and no released version emitted the uppercase ''S'' tag, thus deprecating and ultimately removing the support for the ''S'' tag is exceedingly unlikely to affect anyone.


<doodle title="Deprecate unserialize()’s ‘S’ tag?" auth="timwolla" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== session.sid_length and session.sid_bits_per_character ====

  * Author: Tim Düsterhus <timwolla@php.net>
  * Implementation: https://github.com/php/php-src/pull/15213

PHP’s session extension currently contains two INI settings that allow the administrator to respectively control the length and the possible characters within emitted session IDs.

  * The length may be configured as any value between 22 and 256.
  * The bits per character may be selected to be either 4 (''[0-9a-f]''), 5 (''[0-9a-v]''), or 6 (''[0-9a-zA-Z,-]''), returning the characters indicated by the regular expression character group within the parentheses.

In [[https://github.com/php/php-src/issues/12418|issue #12418]] it was reported that configuring 6 bits per character might generate session IDs that are rejected by WAF applications, such as mod_security. The 6 bits per character configuration might generate session IDs containing dashes, more specifically two consecutive dashes. Within an SQL query two consecutive dashes indicate the start of a comment, which is a common technique when exploiting SQL injection vulnerabilities, leading to a false positive within the WAF and rejecting any requests containing such a session ID.

The default is a 32 character SID, with 4 bits of entropy per character, resulting in a 128-bit session ID. 128 bits of entropy [[https://security.stackexchange.com/a/102163/21705|is generally considered the correct choice for a secret value]]. More is unnecessary and less raises eyebrows. Guessing a 128 Bit value with a probability of 10^-11 would require roughly 2^46 guesses. At 100_000 guesses per second it would take 23 years to even reach this negligible probability.

In other words changing the default values will either generate session IDs that raise eyebrows (4 bits per character with less than 32 characters or 5 bpc for less than 26 characters) or generate session IDs that are needlessly strong, increasing CPU costs, due to the additional randomness required, and increasing the chance for interoperability problems, such as the mod_security example.

For this reason we propose to deprecate the two INI settings in favor of the opinionated choice of the current defaults of a 32 character hexadecimal session ID.

The hexadecimal character set is not expected to cause any interoperability issues, as it is the most limited one of the currently available ones and hexadecimal identifiers are likely the most commonly used. While this would increase the length of the session ID from the previous minimum of 22 characters (which is a secure choice when combined with 6 bits per character) to 32, we do not expect this to be an issue in practice. The difference in traffic is minimal and a hexadecimal session ID is trivially packed into a 16 Byte binary string using <php>hex2bin()</php>, should storage requirements of the session backend be a concern.

<doodle title="Deprecate the INI settings ‘session.sid_length’ and ‘session.sid_bits_per_character’?" auth="timwolla" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Deprecate SplFixedArray::__wakeup() ====

  * Author: Gina Peter Banyard <girgias@php.net>
  * Implementation: https://github.com/php/php-src/pull/9704

<php>SplFixedArray</php> never implemented the <php>__sleep()</php> magic methods and since PHP 8.2 it implements the <php>__serialize()</php> and <php>__unserialize()</php> magic methods, meaning userland classes extending <php>SplFixedArray</php> must override those new methods.

As such the <php>SplFixedArray::__wakeup()</php> is pointless and should be deprecated.

<doodle title="Deprecate SplFixedArray::__wakeup()?" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== xml_set_object() and xml_set_*_handler() with string method names ====

  * Author: Gina Peter Banyard <girgias@php.net>
  * Implementation: https://github.com/php/php-src/pull/15293

The XML extension allows registering callbacks that are invoked when encountering certain XML triggers, such as the start of a new element or a processing instruction, via the relevant <php>xml_set_*_handler()</php> function.

However, these functions also allow setting a method name, as a string, that should be called on the object provided via <php>xml_set_object()</php>. This behaviour is very strange and seems to date prior to the introduction of proper callables for object methods via the <php>[$objInstance, 'methodName']</php> syntax.

The proposal is to deprecate the <php>xml_set_object()</php> function and passing non-callable strings to the <php>xml_set_*_handler()</php> functions. This would also mean to unset a handler the value of <php>null</php> must be used instead of an empty string which is also currently allowed.

<doodle title="Deprecate xml_set_object() and xml_set_*_handler() with string method names" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Deprecate passing null and false to dba_key_split() ====

  * Author: Gina Peter Banyard <girgias@php.net>
  * Implementation: https://github.com/php/php-src/pull/15297

The signature of <php>dba_key_split()</php> is currently <php>function dba_key_split(string|false|null $key): array|false {}</php>.

However, passing <php>null</php> or <php>false</php> to this function will make it immediately return <php>false</php>,
this is the case since at least PHP 5.3, probably earlier.

Moreover, since PHP 8.0, this is the only way for this function to return <php>false</php>.

The proposal is to deprecate passing <php>null</php> and <php>false</php> to the <php>$key</php> parameter, which will allow to clean up the return type of this function in the next major version to just <php>array</php>.

<doodle title="Deprecate passing null and false to dba_key_split()" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Deprecate passing incorrect data types for options to ext/hash functions ====

  * Author: Niels Dossche <nielsdos@php.net>
  * Implementation: https://github.com/php/php-src/commit/74eff98c84b26a8088fb56b5be748a3e0e1da419

Some hash functions in ext/hash allow passing additional options via an array.
The murmur and xxhash family support taking an integer "seed", and xxh3 furthermore allows a string "secret".

There's a problem with the implementation however in the sense that if you pass a "seed" of a type other than an integer or a "secret" of a type other than string, then these options are silently ignored. This was first reported on our bugtracker: https://github.com/php/php-src/issues/10305. This causes bugs because programmers are led to believe that their options are being applied but in reality they're not. The proposal is to deprecate passing incorrect types for these options, and make this scenario throw a ValueError in the next major version of PHP.

To assess the impact I performed two tests: one for xxh3 and one for murmur.
For xxh3, I performed a simple ''grep -rn --include \*.php xxh3'' search in the sources for the top 2K packagist packages. None of them used xxh3 with the options array and so none of them can be affected by this deprecation.
For murmur, I performed a simple ''grep -rn --include \*.php murmur'' search in the sources for the top 2K packagist packages. I found no uses of the hash function with this algorithm.
Although this gives an indication, I expect most usages to be not in libraries but in end users code.

<doodle title="Deprecate passing incorrect data types for options to ext/hash functions" auth="nielsdos" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Constants SUNFUNCS_RET_STRING, SUNFUNCS_RET_DOUBLE, SUNFUNCS_RET_TIMESTAMP ====

  * Author: Jorg Sowa <jorg.sowa@gmail.com>
  * Implementation: https://github.com/php/php-src/pull/12978

The functions <php>date_sunrise()</php>/<php>date_sunset()</php> are [[rfc:deprecations_php_8_1|already deprecated since PHP 8.1]] and will be removed in the next major version.

The proposal is to deprecate constants <php>SUNFUNCS_RET_STRING</php>, <php>SUNFUNCS_RET_DOUBLE</php>, and <php>SUNFUNCS_RET_TIMESTAMP</php> which are used exclusively with those functions.

<doodle title="Deprecate constants SUNFUNCS_RET_STRING, SUNFUNCS_RET_DOUBLE, and SUNFUNCS_RET_TIMESTAMP?" auth="jorg_sowa" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Deprecate proprietary CSV escaping mechanism ====

  * Author: Gina Peter Banyard <girgias@php.net>
  * Implementation: https://github.com/php/php-src/pull/15362

This proposes to enact step 2 of the [[rfc:kill-csv-escaping|Kill proprietary CSV escaping mechanism]] RFC.
Which is to deprecate passing a non-empty string to the <php>$escape</php> parameter to all the CSV related functions, effectively disabling our problematic escaping mechanism.

This issue has once again appeared to cause issues for users as a new [[https://github.com/php/doc-en/issues/3086|GitHub issue]] was raised recently about this topic.


The affected functions are:

  * <php>fputcsv()</php>
  * <php>fgetcsv()</php>
  * <php>str_getcsv()</php>

and the following <php>SplFileObject</php> methods:

  * <php>SplFileObject::setCsvControl()</php>
  * <php>SplFileObject::getCsvControl()</php>
  * <php>SplFileObject::fputcsv()</php>
  * <php>SplFileObject::fgetcsv()</php>

<doodle title="Deprecate passing a non-empty string to the $escape parameter" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Remove E_STRICT error level and deprecate E_STRICT constant ====

  * Authors: Jorg Sowa <jorg.sowa@gmail.com>, Michael Voříšek (mvorisek)
  * Implementation: https://github.com/php/php-src/pull/13053

The <php>E_STRICT</php> error level was primarily used in PHP 5 to point out bad coding practices.
Most of those errors where [[rfc:reclassify_e_strict|reclassified in PHP 7.0]], however it was still in use in-between PHP 7.0 and 7.4 for the [[https://github.com/php/php-src/pull/4406|mysqli extension]] and [[https://github.com/php/php-src/pull/4407|htmlentities() function]], most references to <php>E_STRICT</php> within engine tests were [[https://github.com/php/php-src/pull/4401|removed in a PR in 2019]].

Because this error level has no meaning anymore, we propose to remove the <php>E_STRICT</php> error level and deprecate the <php>E_STRICT</php> constant.

It should be noted that in theory external extensions could still emit a <php>E_STRICT</php> level error, but this seems unlikely.

<doodle title="Remove the E_STRICT Error Level and Deprecate the E_STRICT constant?" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Deprecate strtok() function ====

  * Author: Michael Voříšek (mvorisek)

The <php>strtok()</php> is a wrapper around the C function of the same name and is used to split a string into tokens.

The design of this function is rather problematic and incompatible with named arguments.
The first call to the function requires the string to tokenize and the initial delimiter, while follow-up calls must only provide the next delimiter. As such this function is stateful and stores the string to tokenize and how far along the string it has already tokenized.

This means it is possible to affect the state of this function from different scopes, which is very surprising, unintuitive, and potentially hard to debug (e.g. if the function is called from different fibers, or [[https://3v4l.org/eplIO|from within a function]]).

In general there are more appropriate alternatives such as <php>strpos()</php>, <php>explode()</php>, <php>preg_split()</php>, or writing a proper parser for more complicated situations.

Therefore, we propose to deprecate the <php>strtok()</php> function.

<doodle title="Deprecate strtok()?" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Deprecate returning non-string values from a user output handler ====

  * Author: Gina Peter Banyard <girgias@php.net>

PHP's output buffering mechanism has some quirks due to its age.
One of them is how the return value of a userland callback is treated.
The documentation has indicated for a long time that the callback should return a string, however for most values it will try to cast the return value to a string.
This is an issue because if the return value is an array it will be converted to the string ''Array'' but the warning will be suppressed as the output of the warning has nowhere to go.

Moreover, it treats the values <php>true</php> and <php>false</php> as special.
A return value of <php>true</php> is treated like a context reset, which is identical to returning an empty string.
A return value of <php>false</php> is treated like a failure to process the buffer, which will cause the handler to be disabled and pass the input buffer to the next output handler in the stack.

As the behaviour of returning values other than <php>string</php> from an output buffer is unintuitive we propose deprecating this behaviour.

Return values of <php>true</php> should be changed to an empty string, and if <php>false</php> is returned, we think it would be better to throw an exception instead.

For more information see the documentation: https://www.php.net/manual/en/outcontrol.user-level-output-buffers.php

<doodle title="Deprecate returning non-string values from a user output buffer handler?" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>


==== Deprecate producing output in a user output handler ====

  * Author: Gina Peter Banyard <girgias@php.net>

Because an output handler should just be manipulating the incoming buffer, any output that it produces is discarded.
As such, issues within an output handler can go unnoticed and be hard to debug.

Therefore, we propose deprecating producing any output in an output handler, in the same way as attempting to use an output buffering function in an output handler will emit a Fatal Error.

<doodle title="Deprecate producing output in a user output handler?" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== file_put_contents() with $data as an array ====

  * Author: Gina Peter Banyard <girgias@php.net>

Passing an array as the <php>$data</php> parameter is a surprising and unknown feature of the <php>file_put_contents()</php> function.
However, if the array is not fully comprised of strings a partial write can occur as an exception might occur during the conversion of the value to string, or simply because another file acquired a lock on it.

One potential solution to this problem is to first loop through the values to check that they are strings, however this means looping twice over the values, once to check, a second time to write entry by entry.

Another potential annoyance is that the <php>array</php> type cannot be widened to <php>iterable</php> as there is no reliable way to determine how an object implementing <php>Stringable</php> and <php>Traversable</php> should be interpreted.

An analysis using Exakat on private and public codebases reveals that this feature is barely used only by a few libraries, which seem to boil down to the following:

  * ''symfony/error-handler/DebugClassLoader.php''
  * ''symfony/http-kernel/Profiler/FileProfilerStorage.php''
  * ''laminas/laminas-validator/bin/update_hostname_validator.php''
  * ''scssphp/scssphp/src/Cache.php''

As such, we propose to deprecate using an <php>array</php> for the <php>$data</php> argument of <php>file_put_contents()</php>

The simplest replacement is: <php>file_put_contents($filename, implode('', $data))</php>, however one can also open the file and use a <php>foreach</php> loop to append every individual item.

<doodle title="Deprecate using an array as the $data argument for file_put_contents()" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>


==== mysqli_ping() and mysqli::ping() ====

  * Authors: Gina Peter Banyard <girgias@php.net>, Kamil Tekiela <dharman@php.net>
  * Implementation: https://github.com/php/php-src/pull/11945

The purpose of <php>mysqli_ping()</php> and <php>$mysqli->ping()</php> is to check whether the connection is live and attempt reconnection if it is not. This only works if mysqli is compiled with libmysql. The support for this has been removed in PHP 8.2. 
As it's no longer possible to use automatic reconnection in PHP 8.2, the <php>mysqli_ping()</php> function has become useless. 

For users who simply want to check if the connection is alive, they can use <php>DO 1</php> or similar SQL query to see if it succeeds. There is no need to offer such functionality in PHP anymore.

See reasoning: https://github.com/php/php-src/pull/11912#issuecomment-1671762583

<doodle title="Deprecate mysqli_ping() and mysqli::ping()?" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Deprecate mysqli_refresh() ====

  * Author: Kamil Tekiela <dharman@php.net>
  * Implementation and more explanations can be found at: https://github.com/php/php-src/pull/11929

The <php>mysqli_refresh()</php> function and its OO counterpart <php>$mysqli->refresh()</php> are just a wrapper for the <php>COM_REFRESH</php> command. The <php>COM_REFRESH</php> command has been deprecated as of MySQL 5.7.
The <php>mysqli_refresh()</php> function has very easy alternatives as it's just a binary protocol version of the SQL <php>FLUSH</php> command. On top of this, the FLUSH command accepts more parameters than the COM_REFRESH command, which makes <php>mysqli_refresh()</php> the worse option of the two.

The proposal is to deprecate the <php>mysqli_refresh()</php> function and its OO counterpart, and promote usage of SQL queries, e.g. <php>FLUSH LOGS, FLUSH TABLES, FLUSH HOSTS</php> etc. 

All of the MYSQLI_REFRESH_* constants will be removed too.

<doodle title="Deprecate mysqli_refresh(), mysqli::refresh() and related constants?" auth="dharman" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Deprecate mysqli_kill() ====

  * Author: Kamil Tekiela <dharman@php.net>
  * Implementation: https://github.com/php/php-src/pull/11926

The <php>mysqli_kill()</php> function and its OO counterpart <php>$mysqli->kill()</php> are just a wrapper for the <php>COM_PROCESS_KILL</php> command. The <php>COM_PROCESS_KILL</php> command has been deprecated as of MySQL 5.7.
The usage of this command is to kill a running MySQL process. It's the same as executing <php>KILL processlist_id</php> SQL statement. 

The only issue with deprecating this function in PHP is the way in which it has been used in PHP unit tests.
The <php>mysqli_kill()</php> function has been used in PHP unit tests to kill the same MySQL process that has executed the command, effectively killing itself. 
Using the <php>KILL</php> SQL command would have resulted in PHP throwing an error about interrupted connection, while using the <php>mysqli_kill()</php> function does not.
Suicidal use of this function was unlikely to be an intended use case.
There's no reason to support such behaviour from mysqli. Users who truly need this behaviour can emulate it in userland using the <php>KILL</php> statement.

The proposal is to deprecate the <php>mysqli_kill()</php> function and <php>$mysqli->kill()</php>, in favour of using the <php>KILL</php> statement. 

<doodle title="Deprecate mysqli_kill() and mysqli::kill()?" auth="dharman" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Deprecate the second parameter to mysqli_store_result() ====

  * Author: Kamil Tekiela <dharman@php.net>
  * Implementation: https://github.com/php/php-src/pull/15311

The <php>mysqli_store_result()</php> function used to have second parameter called <php>$mode</php>. As of PHP 8.1, this parameter is no longer used. As this parameter is due for removal in PHP 9.0 and users might unknowingly still use it, the proposal is to deprecate this parameter and the associated constant <php>MYSQLI_STORE_RESULT_COPY_DATA</php>. See https://www.php.net/manual/en/mysqli.store-result.php
 

<doodle title="Deprecate the second parameter to mysqli_store_result()?" auth="dharman" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Deprecate lcg_value() ====

  * Author: Tim Düsterhus <timwolla@php.net>
  * Implementation: https://github.com/php/php-src/pull/15211

The <php>lcg_value()</php> function is documented to return “A pseudo random float value between 0.0 and 1.0, inclusive” and also “lcg_value() returns a pseudo random number in the range of (0, 1)”, the latter of which is generally understood as an open interval, excluding the boundary values, indicated by the use of round parentheses. This makes the documentation about the returned range contradict itself.

Looking at the implementation, the function is able to return one of 2147483562 different floats between ''4.6566130000000002e-10'' and ''0.99999832898966134'' (both inclusive). The returned floats are however //not// uniformly distributed within this interval, because the internal step size ''4.6566128730773926e-10'' that transform a randomly generated integer between 1 and 2147483562 into a float does not always result in a float that can be represented exactly, resulting in effective distances of ''4.6566128730773926e-10'' for most results, ''4.6566139833004172e-10'' for others and a much smaller distance of ''1.2790449366306689e-08'' between the highest possible return value and ''1.0''.

The internally used “Combined LCG” RNG to generate the random integer between ''1'' and ''2147483562'' cannot be usefully be used for any other purpose, for example generating uniformly selected integers, either, because it cannot generate ''0'' and because the upper bound is not a value directly below a power of two, requiring expensive post-processing compared to the other engines available to userland (Mt19937, Xoshiro256StarStar, and PcgOneseq128XslRr64).

Furthermore the current implementation makes it possible for the seeding to generate degenerate internal states that either cut the period short, prevent some of results from being returned, or may generate a zero value.

The current state of the function makes it unfit for any serious usage, returning uniformly distributed results is the bare minimum one expects from a random number generator, unless a specific distribution is requested.

While it would be possible to fix the internal implementation as the RNG is not seedable from userland, this would technically still be a breaking change and it would not really improve the situation for the end user.

Even when the function would generate a uniformly generated integer between 0 and 1 (both excluded) to keep main semantics the current interval boundaries, the results would not be particularly useful. Expanding the values onto a larger interval would re-introduce a bias, as explained in the warning box on the [[https://www.php.net/manual/en/random-randomizer.nextfloat.php|documentation page for ''\Random\Randomizer::nextFloat()'']]. Generating values from an open interval as a building block is also much less useful compared to a right-open interval that would include the lower bound as a possible return value.

Furthermore the function name is not particularly well-chosen. It does not indicate what the function does and references the underlying Combined LCG as an implementation detail within the ''lcg_'' prefix of the function name.

Since PHP 8.3, PHP provides <php>\Random\Randomizer::getFloat()</php> as a safe solution to generate uniformly distributed floats within arbitrary intervals.

As the function cannot be used in a safe way, except possibly for obscure use-cases, we propose the deprecation of it. It is possible to polyfill the functionality for users that rely on this peculiar behavior. An implementation based on the CSPRNG that avoids the issues of the Combined LCG would be as follows:

<PHP>
function lcg_value(): float {
  return random_int(1, 2147483562) * 4.656613e-10;
}
</PHP>

<doodle title="Deprecate lcg_value()?" auth="timwolla" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Deprecate uniqid() ====

  * Author: Tim Düsterhus <timwolla@php.net>

The <php>uniqid()</php> function is documented to “Generate a unique ID”. The documentation further expands on this that the returned value is a “[…] timestamp based unique identifier as a string”. In other words, the <php>uniqid()</php> function is just a formatter for the current time.

While the <php>uniqid()</php> function makes sure to not generate the same timestamp for two consecutive calls, it nevertheless is incapable of actually guaranteeing that a unique ID is generated:

    * Concurrent requests, for example by using multiple php-fpm workers on the same system, or when running the application on multiple servers, might call <php>uniqid()</php> at exactly the same point in time.
    * An NTP client might move the clock backwards, for example if the hardware clock of the system in question is ticking too fast.

The function also takes a <php>$prefix</php> parameter, which as per the documentation may be used to, for example, ensure per-host IDs by adding a hostname prefix to every generated ID. This however does not protect against the clock moving backwards and is also hard to apply to separate multiple FPM workers within the same pool. It also requires manual effort on the user’s end to make the function safe to use.

Likewise the function also provides a <php>$more_entropy</php> parameter adding at most 32 bits of entropy to distinguish different values generated in the same microsecond. 32 bits of randomness is generally insufficient to guarantee uniqueness in the long term, especially if generated IDs are shared outside of a single application with other applications also leveraging <php>uniqid()</php>. As a comparison: The two behaviorally closest ID standards, UUIDv7 and ULIDs only use a timestamp with millisecond precision, but include 80 bits of randomness, resulting in 38 bits of effective additional randomness compared to <php>uniqid()</php>.

A GitHub search for ''"uniqid()" language:PHP'' reveals 136k results where <php>uniqid()</php> is not called with the <php>$more_entropy</php> parameter set to <php>true</php>, which is the bare minimum to consider the usage safe. Right on the first page of the results, a bare call to <php>uniqid()</php> is [[https://github.com/HackerExperience/legacy/blob/5605b69400f9d91e951e71336e53c7040983d628/reset.php#L36|used to generate a security-sensitive “email reset” token]] that is trivially guessable by knowing when the token was generated.

However even when specifying <php>$more_entropy</php> as <php>true</php>, <php>uniqid()</php> is often used in places where an //unguessable// rather than just a unique value is required. The previously mentioned “email reset” token would be such a place. Enumerating the 32 bits of randomness added is trivial for an attacker. Often complex, but ultimately meaningless, constructions, such as passing the output of <php>uniqid()</php> [[https://github.com/manxoom/Ecommerce/blob/88b50675007ecc86bef8320e4be760e540c3277c/cart.php#L11|through a hash function]], are used. The use of a hash function does not increase the unpredictability of the underlying value, because it cannot add entropy.

As users rely on <php>uniqid()</php>’s output format, it is not possible to adjust the behavior to make the function safer to use, except by adding more optional parameters that users will need to remember to add.

While there may be situations where <php>uniqid()</php> can safely be used, they are few and far between. The results of the GitHub search make it clear that users inappropriately use <php>uniqid()</php> for security-sensitive code, despite the warnings in the documentation. We expect most of them to be better served by using a purpose-built solution to safely generate a random string or random identifier.

This includes:

  * <php>\bin2hex(\random_bytes(16))</php> to generate a printable and secure random string (e.g. an access token).
  * The ramsey/uuid library to generate database identifiers.
  * PHP’s <php>\Random\Randomizer::getBytesFromString()</php> method to generate random strings with a specific format.
  * PHP’s <php>\DateTimeImmutable::format()</php> method to generate a time-based string when uniqueness is only a best-effort requirement.
  * PHP’s <php>tempnam()</php> function to generate a filename for a temporary file. Incidentally the [[https://github.com/php/php-src/pull/14364|amount of randomness of this function has been increased in PHP 8.4]], to prevent a possible attack vector using guessable filenames.
  * PHP’s <php>tmpfile()</php> function if just a temporary file handle (without knowing the filename) is required.

To gently nudge users away from <php>uniqid()</php> towards safer or more-standard alternatives in newly written code, we propose to deprecate <php>uniqid()</php>.

We acknowledge that there is a vast collection of existing code that uses <php>uniqid()</php>. While it is likely often the case that these usages are unsafe and should be replaced, this may not necessarily easy, due to consumers expecting a specific ID format. As such the removal of <php>uniqid()</php> will likely have a large impact on existing code to the point where users will hold off upgrading their PHP versions to not break their application.

As the internal implementation of <php>uniqid()</php> is low-maintenance and does not otherwise interact with the language’s behavior, keeping <php>uniqid()</php> available indefinitely is possible. Therefore we propose just a deprecation, **without any specific plans for the removal** of the <php>uniqid()</php> function. To ease planning on the user’s end, the <php>uniqid()</php> function shall remain available for at least 5 years or at least another full major version cycle, whichever is longer. This means it **may be removed in PHP 10 at the earliest** and the removal shall be part of a fresh RFC vote.

A polyfill (64 bit PHP only) is as follows:

<PHP>
function my_uniqid(string $prefix = '', bool $more_entropy = false) {
	static $last = null;
	do {
		$microtime = \microtime();
	} while ($microtime === $last);
	$last = $microtime;

	[$usec, $sec] = \explode(" ", $microtime, 2);
	$usec = \substr($usec, 2);
	$usec %= 0x100000;

	if ($more_entropy) {
		$seed = (((float)random_int(0, 4294967295)) / 4294967295) * 10.0;

		return \sprintf("%s%08x%05x%.8F", $prefix, $sec, $usec, $seed);
	} else {
		return \sprintf("%s%08x%05x", $prefix, $sec, $usec);
	}
}
</PHP>

<doodle title="Deprecate uniqid()?" auth="timwolla" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Deprecate md5(), sha1(), md5_file(), and sha1_file() ====

  * Author: Tim Düsterhus <timwolla@php.net>

The cryptographic checksum MD5 and SHA-1 are considered broken for their main use of verifying the authenticity of a a payload or message and should be replaced by a hash function from the SHA-2 family (e.g. SHA-256) or another cryptographic hash function that is still considered to be secure.

Unfortunately these cryptographically secure hash functions are only available by means of the generic <php>hash()</php> function (and the closely related <php>hash_init()</php>, <php>hash_file()</php>, and <php>hash_hmac</php> functions), making using them more verbose and thus seemingly more complicated than the standalone <php>md5()</php>, <php>sha1()</php>, <php>md5_file()</php>, and <php>sha1_file()</php> functions, which likely are available as standalone functions for historic versions only - the ext/hash extension is only required as of PHP 7.4 - and also do not support the incremental hashing by means of the <php>hash_init()</php> functionality. 

To encourage users to use a secure hash functions, instead of using an insecure algorithm, because the code is shorter, we propose to deprecate standalone functions. This also keeps the documentation simpler, because these closely related functions do not each need to be explained by themselves and also slims down the list of functions in the standard library.

Users may replace the use of the standalone functions as follows if they still require the use of MD5 and SHA-1:

  * <php>md5($data, $binary = false)</php> → <php>hash('md5', $data, $binary = false)</php>
  * <php>sha1($data, $binary = false)</php> → <php>hash('sha1', $data, $binary = false)</php>
  * <php>md5_file($filename, $binary = false)</php> → <php>hash_file('md5', $filename, $binary = false)</php>
  * <php>sha1_file($filename, $binary = false)</php> → <php>hash_file('sha1', $filename, $binary = false)</php>

Only the standalone functions shall be deprecated. The MD5 and SHA-1 algorithm shall remain available without deprecations by means of the <php>hash()</php> function family. Despite being insecure for verifying the authenticity of a payload, there are use cases that are still considered secure and using the MD5 and SHA-1 algorithms might also be necessary for interoperability with existing legacy systems.

We acknowledge that there is a vast collection of existing code that uses these standalone functions. As such the removal of them will likely have a large impact on existing code, despite there being a direct replacement that can be automated with tools such as Rector or using IDE assistance.

As the internal implementation of these standalone functions is low-maintenance and does not otherwise interact with the language’s behavior, keeping them available indefinitely is possible. Therefore we propose just a deprecation, **without any specific plans for the removal** of the standalone functions. To ease planning on the user’s end, the standalone functions shall remain available for at least 5 years or at least another full major version cycle, whichever is longer. This means it **may be removed in PHP 10 at the earliest** and the removal shall be part of a fresh RFC vote.

<doodle title="Deprecate md5(), sha1(), md5_file(), and sha1_file()?" auth="timwolla" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Deprecate passing E_USER_ERROR to trigger_error() ====

  * Author: Gina Peter Banyard <girgias@php.net>
  * Implementation: https://github.com/php/php-src/pull/15308

Using <php>E_USER_ERROR</php> with <php>trigger_error()</php> triggers PHP's bailout mechanism,
which means that it triggers the equivalent of a Fatal Error.
This mechanism is generaly reserved for severe engine failures, such as being unable to allocate memory.

The problems of the bailout mechanism is explained in detail in the [[https://wiki.php.net/rfc/engine_exceptions_for_php7#issues_with_fatal_errors|"Issues with fatal errors" section of the Exceptions in the engine (for PHP 7)]] RFC.
Some of them are:

  * <php>finally</php> blocks are not executed
  * Destructors are not executed

Moreover, it is in theory possible to "catch" a E_USER_ERROR via an error handler defined with <php>set_error_handler()</php>
by returning <php>true</php>, this is problematic as the execution will be returned to the code that called <php>trigger_error()</php>.
Which it is unlikely to be able to handle.

Using exceptions instead solves all the above problems, and allows catching the error outside the problematic code path.

If the desired outcome is to terminate the program with no possible way to recover one should use the <php>exit()</php> function with a string argument.

Therefore we propose to deprecate passing <php>E_USER_ERROR</php> to <php>trigger_error()</php>

<doodle title="Deprecate passing E_USER_ERROR to trigger_error()" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Deprecate using a single underscore ''_'' as a class name ====

  * Author: Gina Peter Banyard <girgias@php.net>
  * Implementation: https://github.com/php/php-src/pull/15360

Currently class names must be a valid label name (meaning they follow the same rules as variables and function names) and thus can start with an underscore ''_''.
It may also be *just* an underscore:
<PHP>
class _ {}
</PHP>

The main motivation to deprecate using a single underscore ''_'' as a class name is that ''_'' conflicts with a potential wildcard pattern for the [[rfc:pattern-matching|Pattern Matching RFC]], which is generally the token used for such a wildcard in other programming languages that support pattern matching.
 
The impact of this deprecation should be non-existent.
An analysis using Exakat revealed that no one uses a class name of ''_''.

<doodle title="Deprecate using a single underscore as a class name?" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

==== Deprecate SOAP_FUNCTIONS_ALL constant and passing it to SoapServer::addFunction() ====

  * Author: Gina Peter Banyard <girgias@php.net>
  * Implementation: https://github.com/php/php-src/pull/15310

The <php>SOAP_FUNCTIONS_ALL</php> constant's sole purpose is to make all PHP functions available to client to use on the SOAP server.

This is of dubious use and potential security issue.

We therefore propose deprecating this function and passing an integer to <php>SoapServer::addFunction()</php> as the only valid integer value it accepts is <php>SOAP_FUNCTIONS_ALL</php>.

<doodle title="Deprecate SOAP_FUNCTIONS_ALL constant and passing it to SoapServer::addFunction()?" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== Backward Incompatible Changes =====

For PHP 8.4 additional deprecation notices will be emitted. The actual removal of the affected functionality will happen no earlier than PHP 9.

===== Removed from this proposal =====

The following entries were originally added to this proposal and then dropped.


==== Constant SID ====

This was deprecated as part of [[rfc:deprecate-get-post-sessions|Deprecate GET/POST sessions]] RFC.


==== Deprecate E_USER_ERROR constant ====

This is removed to be tackled as a later point in time as not to affect the error_reporting INI setting and corresponding function.
Page Tools
