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:
DOMDocument and DOMEntity propertiesDOMImplementation::getFeature($feature, $version)DOM_PHP_ERR Constantunserialize()'s 'S' tagsession.sid_length and session.sid_bits_per_characterSplFixedArray::__wakeup()xml_set_object() and xml_set_*_handler() with string method namesSUNFUNCS_RET_STRING, SUNFUNCS_RET_DOUBLE, SUNFUNCS_RET_TIMESTAMPE_STRICT Constantstrtok()file_put_contents() with $data as an arraymysqli_ping() and mysqli::ping()mysqli_refresh()mysqli_kill()mysqli_store_result()lcg_value()uniqid()E_USER_ERROR to trigger_error()_ as a class nameSOAP_FUNCTIONS_ALL constant and passing it to SoapServer::addFunction()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).
The following properties have been soft-deprecated for at least 17 years:
DOMDocument::$actualEncoding: it is just an alias to DOMDocument::$encodingDOMDocument::$config: it has always returned nullDOMEntity::$actualEncoding: it has always returned nullDOMEntity::$encoding: it has always returned nullDOMEntity::$version: it has always returned nullAs such we propose to formally deprecate them.
DOMImplementation::getFeature($feature, $version) 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.
PR https://github.com/php/php-src/pull/11927 got rid of the last use of DOM_PHP_ERR 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 INVALID_STATE_ERR for that.
GitHub search reveals 174 matches (as of Jan 20 2024) for DOM_PHP_ERR. There are occurrences in string-form, i.e. "DOM_PHP_ERR" 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.
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 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 in a follow-up commit and support for that uppercase S tag 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.
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.
[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 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 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 hex2bin(), should storage requirements of the session backend be a concern.
SplFixedArray never implemented the __sleep() magic methods and since PHP 8.2 it implements the __serialize() and __unserialize() magic methods, meaning userland classes extending SplFixedArray must override those new methods.
As such the SplFixedArray::__wakeup() is pointless and should be deprecated.
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 xml_set_*_handler() function.
However, these functions also allow setting a method name, as a string, that should be called on the object provided via xml_set_object(). This behaviour is very strange and seems to date prior to the introduction of proper callables for object methods via the [$objInstance, 'methodName'] syntax.
The proposal is to deprecate the xml_set_object() function and passing non-callable strings to the xml_set_*_handler() functions. This would also mean to unset a handler the value of null must be used instead of an empty string which is also currently allowed.
The signature of dba_key_split() is currently function dba_key_split(string|false|null $key): array|false {}.
However, passing null or false to this function will make it immediately return false,
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 false.
The proposal is to deprecate passing null and false to the $key parameter, which will allow to clean up the return type of this function in the next major version to just array.
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.
The functions date_sunrise()/date_sunset() are already deprecated since PHP 8.1 and will be removed in the next major version.
The proposal is to deprecate constants SUNFUNCS_RET_STRING, SUNFUNCS_RET_DOUBLE, and SUNFUNCS_RET_TIMESTAMP which are used exclusively with those functions.
This proposes to enact step 2 of the Kill proprietary CSV escaping mechanism RFC.
Which is to deprecate passing a non-empty string to the $escape 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 GitHub issue was raised recently about this topic.
The affected functions are:
and the following SplFileObject methods:
The E_STRICT error level was primarily used in PHP 5 to point out bad coding practices.
Most of those errors where reclassified in PHP 7.0, however it was still in use in-between PHP 7.0 and 7.4 for the mysqli extension and htmlentities() function, most references to E_STRICT within engine tests were removed in a PR in 2019.
Because this error level has no meaning anymore, we propose to remove the E_STRICT error level and deprecate the E_STRICT constant.
It should be noted that in theory external extensions could still emit a E_STRICT level error, but this seems unlikely.
The strtok() 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 from within a function).
In general there are more appropriate alternatives such as strpos(), explode(), preg_split(), or writing a proper parser for more complicated situations.
Therefore, we propose to deprecate the strtok() function.
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 true and false as special.
A return value of true is treated like a context reset, which is identical to returning an empty string.
A return value of false 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 string from an output buffer is unintuitive we propose deprecating this behaviour.
Return values of true should be changed to an empty string, and if false 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
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.
Passing an array as the $data parameter is a surprising and unknown feature of the file_put_contents() 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 array type cannot be widened to iterable as there is no reliable way to determine how an object implementing Stringable and Traversable 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.phpsymfony/http-kernel/Profiler/FileProfilerStorage.phplaminas/laminas-validator/bin/update_hostname_validator.phpscssphp/scssphp/src/Cache.php
As such, we propose to deprecate using an array for the $data argument of file_put_contents()
The simplest replacement is: file_put_contents($filename, implode('', $data)), however one can also open the file and use a foreach loop to append every individual item.
The purpose of mysqli_ping() and $mysqli->ping() 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 mysqli_ping() function has become useless.
For users who simply want to check if the connection is alive, they can use DO 1 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
The mysqli_refresh() function and its OO counterpart $mysqli->refresh() are just a wrapper for the COM_REFRESH command. The COM_REFRESH command has been deprecated as of MySQL 5.7.
The mysqli_refresh() function has very easy alternatives as it's just a binary protocol version of the SQL FLUSH command. On top of this, the FLUSH command accepts more parameters than the COM_REFRESH command, which makes mysqli_refresh() the worse option of the two.
The proposal is to deprecate the mysqli_refresh() function and its OO counterpart, and promote usage of SQL queries, e.g. FLUSH LOGS, FLUSH TABLES, FLUSH HOSTS etc.
All of the MYSQLI_REFRESH_* constants will be removed too.
The mysqli_kill() function and its OO counterpart $mysqli->kill() are just a wrapper for the COM_PROCESS_KILL command. The COM_PROCESS_KILL 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 KILL processlist_id 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 mysqli_kill() function has been used in PHP unit tests to kill the same MySQL process that has executed the command, effectively killing itself.
Using the KILL SQL command would have resulted in PHP throwing an error about interrupted connection, while using the mysqli_kill() 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 KILL statement.
The proposal is to deprecate the mysqli_kill() function and $mysqli->kill(), in favour of using the KILL statement.
The mysqli_store_result() function used to have second parameter called $mode. 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 MYSQLI_STORE_RESULT_COPY_DATA. See https://www.php.net/manual/en/mysqli.store-result.php
The lcg_value() 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 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 \Random\Randomizer::getFloat() 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:
function lcg_value(): float { return random_int(1, 2147483562) * 4.656613e-10; }
The uniqid() 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 uniqid() function is just a formatter for the current time.
While the uniqid() 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:
uniqid() at exactly the same point in time.
The function also takes a $prefix 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 $more_entropy 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 uniqid(). 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 uniqid().
A GitHub search for “uniqid()” language:PHP reveals 136k results where uniqid() is not called with the $more_entropy parameter set to true, which is the bare minimum to consider the usage safe. Right on the first page of the results, a bare call to uniqid() is used to generate a security-sensitive “email reset” token that is trivially guessable by knowing when the token was generated.
However even when specifying $more_entropy as true, uniqid() 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 uniqid() 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 uniqid()’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 uniqid() can safely be used, they are few and far between. The results of the GitHub search make it clear that users inappropriately use uniqid() 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:
\bin2hex(\random_bytes(16)) to generate a printable and secure random string (e.g. an access token).\Random\Randomizer::getBytesFromString() method to generate random strings with a specific format.\DateTimeImmutable::format() method to generate a time-based string when uniqueness is only a best-effort requirement.tempnam() function to generate a filename for a temporary file. Incidentally the amount of randomness of this function has been increased in PHP 8.4, to prevent a possible attack vector using guessable filenames.tmpfile() function if just a temporary file handle (without knowing the filename) is required.
To gently nudge users away from uniqid() towards safer or more-standard alternatives in newly written code, we propose to deprecate uniqid().
We acknowledge that there is a vast collection of existing code that uses uniqid(). 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 uniqid() 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 uniqid() is low-maintenance and does not otherwise interact with the language’s behavior, keeping uniqid() available indefinitely is possible. Therefore we propose just a deprecation, without any specific plans for the removal of the uniqid() function. To ease planning on the user’s end, the uniqid() 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:
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); } }
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 hash() function (and the closely related hash_init(), hash_file(), and hash_hmac functions), making using them more verbose and thus seemingly more complicated than the standalone md5(), sha1(), md5_file(), and sha1_file() 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 hash_init() 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:
Only the standalone functions shall be deprecated. The MD5 and SHA-1 algorithm shall remain available without deprecations by means of the hash() 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.
Using E_USER_ERROR with trigger_error() 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 "Issues with fatal errors" section of the Exceptions in the engine (for PHP 7) RFC. Some of them are:
finally blocks are not executed
Moreover, it is in theory possible to “catch” a E_USER_ERROR via an error handler defined with set_error_handler()
by returning true, this is problematic as the execution will be returned to the code that called trigger_error().
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 exit() function with a string argument.
Therefore we propose to deprecate passing E_USER_ERROR to trigger_error()
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:
class _ {}
The main motivation to deprecate using a single underscore _ as a class name is that _ conflicts with a potential wildcard pattern for the 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 _.
The SOAP_FUNCTIONS_ALL 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 SoapServer::addFunction() as the only valid integer value it accepts is SOAP_FUNCTIONS_ALL.
For PHP 8.4 additional deprecation notices will be emitted. The actual removal of the affected functionality will happen no earlier than PHP 9.
The following entries were originally added to this proposal and then dropped.
This was deprecated as part of Deprecate GET/POST sessions RFC.
This is removed to be tackled as a later point in time as not to affect the error_reporting INI setting and corresponding function.