====== PHP RFC: Deprecations for PHP 8.6 ======
  * Date: 2025-10-12
  * Authors:
    * Gina Peter Banyard <girgias@php.net>
    * Alexandre Daubois <alexandredaubois@php.net>
  * Status: Draft
  * Implementation: 8.6
    * TBD

===== Introduction =====

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

  * Passing objects for <php>$array</php> parameter of <php>array_walk()</php> and <php>array_walk_recursive()</php>
  * Passing objects for <php>$options</php> parameter of <php>deflate_init()</php> and <php>inflate_init()</php>
  * Passing objects to <php>ArrayObject::exchangeArray()</php>
  * Deprecate <php>strcoll()</php>
  * Deprecate <php>SORT_LOCALE_STRING</php> flag for <php>sort()</php> functions
  * Providing invalid values to <php>log()</php> second argument
  * Providing an invalid sorting order to <php>scandir()</php>
  * Providing invalid values to "work" and "blocks" options of the "bzip2.compress" filter
  * Deprecate <php>mail.add_x_header</php> INI setting
  * Deprecate <php>mysqli::stmt_init</php>

===== Proposal =====

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

==== Example Deprecation ====

  * Author: Name <name@example.com>

Description


==== Passing objects for $array parameter of array_walk() and array_walk_recursive() ====

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

TODO: Reason to get rid of 'A' ZPP specifier
Fallback: <php>get_object_vars()</php>

The recursive version doesn't recursive if a value/property is an object.
Due to taking by reference this breaks readonly properties, which is a similar issue that the ArrayObject with backing object deprecation is addressing


==== Passing objects for $options parameter of deflate_init() and inflate_init() ====

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

TODO: Reason to get rid of 'H' ZPP specifier
Fallback: <php>get_object_vars()</php>


==== Passing objects to ArrayObject::exchangeArray() ====

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

TODO: Follow-up of 8.5 ArrayObject with objects deprecation
https://wiki.php.net/rfc/deprecations_php_8_5#deprecate_arrayobject_and_arrayiterator_with_objects

==== Deprecate strcoll() ====

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

TODO:
  * Not binary safe
  * Relies on global state from <php>setlocale()</php>
  * Alternative: <php>Collator::compare()</php>

==== Deprecate SORT_LOCALE_STRING flag for sort() functions ====

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

TODO:
  * Not binary safe, as internally it relies on the same behaviour as <php>strcoll</php>
  * Relies on global state from <php>setlocale()</php>
  * Alternative: <php>Collator::sort()</php>, <php>Collator::asort()</php>, <php>Collator::sort()</php>, <php>Collator::sortWithSortKeys()</php>

==== Providing invalid values to log() second argument ====

  * Author: Alexandre Daubois <alexandredaubois@php.net>

Providing 1 or any number less or equal to 0 results on a NaN result. This is error-prone. Deprecating then throwing a <php>ValueError</php> in PHP 9.0 would help early error detection and avoid propagating a NaN value.

==== Providing an invalid sorting order to scandir() ====

  * Author: Alexandre Daubois <alexandredaubois@php.net>

Providing an invalid value to the flags of <php>scandir()</php>'s sorting order is currently ignored and falls back to default values. Deprecating such behavior then throwing a <php>ValueError</php> in PHP 9.0 would help error detection and avoid undesired behavior when an invalid value is provided.

==== Providing invalid values to "work" and "blocks" options of the "bzip2.compress" filter ====

  * Author: Alexandre Daubois <alexandredaubois@php.net>

Providing invalid values to the <php>work</php> and <php>blocks</php> options currently silently fails and falls back to default values when using the stream filter <php>bzip2.compress</php>. This may lead to unexpected behavior and difficult error detection. A too low value for <php>work</php>, a too high value for <php>work</php>, a too low value for <php>blocks</php> and a too high value for <php>blocks</php> should be deprecated and will throw a <php>ValueError</php> in PHP 9.0.


==== Deprecate mail.add_x_header INI setting ====

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

TODO: 

This is one of PHP's "expose yourself" INI settings that adds a ''X-PHP-Originating-Script'' header to every email send via the internal <php>php_mail()</php> function (called by <php>mail</php>, <php>error_log()</php>, and <php>mb_mail()</php>).

It is off by default, and we don't see any reason why one would enable it.
Moreover, it is trivially done by adding the header in the corresponding header parameter as followed:

<PHP>
mail("To", "Subject", "Message", ['X-PHP-Originating-Script' => getmyuid() . ':' . basename(__SELF__)]);
</PHP>

==== Deprecate <php>mysqli::stmt_init</php> ====

  * Author: Kamil Tekiela

There doesn't seem to be a good reason for this function to exist. All it does is create a barren `mysqli_stmt` object that still needs to be prepared before use. It is the source of many ways in which mysqli objects can be left in an inconsistent state. It looks like it is only used in PHP unit tests, and in most cases for no good reason. Since this function doesn't provide any tangible value and leads to confusing code, it should be removed to reduce language complexity. 


<PHP>
$stmt = $mysqli->stmt_init();
$stmt->prepare($sql);
// To:
$stmt = $mysqli->prepare($sql);
</PHP>

An alternative and almost unknown way of calling this function is through the constructor, which is equally useless. This proposal includes the deprecation of this feature, i.e. calling <php>mysqli_stmt::__construct</php> without the second argument. 

<PHP>
$stmt = new mysqli_stmt($mysqli);
$stmt->prepare($sql);
// To:
$stmt = new mysqli_stmt($mysqli, $sql);
</PHP>

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

For PHP 8.6 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.