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
• Status: Draft
• Implementation: TBD

The RFC proposes to deprecate the listed functionality in PHP 8.4 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:

• Soft-deprecated DOMDocument and DOMEntity properties
• DOMImplementation::getFeature($feature, $version)
• Constant DOM_PHP_ERR
• mysqli_ping() and mysqli::ping()
• unserialize()'s 'S' tag
• session.sid_length and session.sid_bits_per_character
• SID constant
• SplFixedArray::__wakeup()
• xml_set_object() and xml_set_*_handler() with string method names
• Passing null and false to dba_key_split()
• Non-numeric seed strings in xxh3
• Constants SUNFUNCS_RET_STRING, SUNFUNCS_RET_DOUBLE, SUNFUNCS_RET_TIMESTAMP
• Deprecate proprietary CSV escaping mechanism
• Constant E_STRICT
• Deprecate return invalid types for user output handler callables
• file_put_contents() with $data as an array
• Deprecate mysqli_refresh()
• Deprecate mysqli_kill()

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.

Author: Máté Kocsis kocsismate@php.net

The following properties have already been soft-deprecated for a long time:

• DOMDocument::$actualEncoding: it is just an alias to DOMDocument::$encoding
• DOMDocument::$config: it has always returned null
• DOMEntity::$actualEncoding: it has always returned null
• DOMEntity::$encoding: it has always returned null
• DOMEntity::$version: it has always returned null

Author: Niels Dossche nielsdos@php.net

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.

Author: Niels Dossche nielsdos@php.net

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.

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

Pull request: https://github.com/php/php-src/pull/11945

Author: Tim Düsterhus timwolla@php.net

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.

Implementation: https://github.com/php/php-src/pull/12309

TODO: https://github.com/php/php-src/issues/12418#issuecomment-1763034403

Author: Máté Kocsis kocsismate@php.net

Constant SID is created when a session is initialized, containing the current session ID. Unlike other constants value, it changes to the new ID when php_session_reset_id() is called. This behavior contradicts to any other well behaved constants, therefore it's deprecated.

TODO: https://github.com/php/php-src/pull/9704

Author: Gina Peter Banyard girgias@php.net

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 witch is also currently allowed.

Author: Gina Peter Banyard girgias@php.net

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.

TODO: https://github.com/php/php-src/issues/10305

Author: Jorg Sowa jorg.sowa@gmail.com

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, SUNFUNCS_RET_TIMESTAMP which are used exclusively with those functions.

Implementation: https://github.com/php/php-src/pull/12978

Author: Gina Peter Banyard girgias@php.net

TODO: Follow-up on https://wiki.php.net/rfc/kill-csv-escaping

See: https://github.com/php/doc-en/issues/3086

Author of implementation: mvorisek

RFC author: Jorg Sowa jorg.sowa@gmail.com

The error level E_STRICT has no meaning since PHP 7.0 after changing it to other error levels. It was left for better compatibility.

Implementation: https://github.com/php/php-src/pull/13053

[NOTE FROM GINA: This is incorrect, there were still some usages in PHP 7.4 that I removed, also in theory extensions could still emit it]

Author: Gina Peter Banyard girgias@php.net

It doesn't enforce the return type of string|false (false has special meaning here which is unfortunate) converts true to an empty string. Other implementation bug is suppressing the Array conversion warning due to how the outputs are being buffered/written

See https://github.com/php/doc-en/pull/3126#discussion_r1460917389

Author: Gina Peter Banyard girgias@php.net

TODO: this is surprising, not widely used, and cannot support iterable as how should an object implementing Stringable and Traversable be interpreted

Author: Kamil Tekiela dharman@php.net

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.

Implementation and more explanations can be found at: https://github.com/php/php-src/pull/11929

Author: Kamil Tekiela dharman@php.net

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.

Implementation: https://github.com/php/php-src/pull/11926

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