====== PHP RFC: Deprecations for PHP 8.6 ======
  * Date: 2025-10-12
  * Authors:
    * Gina Peter Banyard <girgias@php.net>
    * Alexandre Daubois <alexandredaubois@php.net>
    * Jordi Kroon <jordikroon@me.com>
  * 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>
  * Deprecate <php>CURLOPT_PROGRESSFUNCTION</php> for <php>curl_setopt()</php>
  * Deprecate <php>is_double()</php>, an alias of <php>is_float()</php>
  * Deprecate <php>is_integer()</php>, an alias of <php>is_int()</php>
  * Deprecate <php>is_long()</php>, an alias of <php>is_int()</php>
  * Deprecate <php>doubleval()</php>, an alias of <php>floatval()</php>
  * Deprecate returning a value from <php>__construct()</php>
  * Deprecate <php>mysqli_get_charset()</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 mysqli::stmt_init ====

  * Author: Kamil Tekiela

There is no justified reason for this function to exist. All it does is create a barren <php>mysqli_stmt</php> 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>

If accepted, calling <php>mysqli::stmt_init()</php> will emit a deprecation notice:

<blockquote>
Deprecated: Function mysqli::stmt_init() is deprecated, use mysqli::prepare() instead
</blockquote>

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>

If accepted, calling <php>new mysqli_stmt()</php> without the second argument will emit a deprecation notice:

<blockquote>
Deprecated: Instantiation of mysqli_stmt without providing the $query parameter is deprecated
</blockquote>

==== Deprecate is_double() ====

  * Author: Jordi Kroon <jordikroon@me.com>

Following the [[rfc: deprecations_php_8_5#deprecate_non-standard_cast_names|deprecation of non standard cast names in PHP 8.5]], it is consistent to consider deprecating legacy aliases which preserve the same non canonical type terminology.

<php>is_double()</php> is a legacy alias of <php> is_float()</php>. The name originates from historical internal naming and platform specific integer sizing, but it no longer communicates anything useful to userland code.

Modern PHP presents the scalar type as <php>float</php>, and the canonical predicate is <php>is_float()</php>. Having <php>is_double()</php> as an additional alias offers no functional value and keeps outdated terminology alive.

This proposal deprecates <php>is_double()</php> and recommends using <php>is_float()</php> instead.

<PHP>
if (is_double($value)) {
    // ...
}
// To:
if (is_float($value)) {
    // ...
}
</PHP>

If accepted, calling <php>is_double()</php> will emit a deprecation notice:

<blockquote>
Deprecated: Function is_double() is deprecated, use is_float() instead
</blockquote>


==== Deprecate is_integer() ====

  * Author: Jordi Kroon <jordikroon@me.com>

Following the [[rfc: deprecations_php_8_5#deprecate_non-standard_cast_names|deprecation of non standard cast names in PHP 8.5]], it is consistent to consider deprecating legacy aliases which preserve the same non canonical type terminology.

<php>is_integer()</php> is a legacy alias of <php>is_int()</php>. The name originates from historical internal naming and platform specific integer sizing, but it no longer communicates anything useful to userland code.

Modern PHP presents the scalar type as <php>int</php>, and the canonical predicate is <php>is_int()</php>. Having <php>is_integer()</php> as an additional alias offers no functional value and keeps outdated terminology alive.

This proposal deprecates <php>is_integer()</php> and recommends using <php>is_int()</php> instead.

<PHP>
if (is_integer($value)) {
    // ...
}
// To:
if (is_int($value)) {
    // ...
}
</PHP>

If accepted, calling <php>is_integer()</php> will emit a deprecation notice:

<blockquote>
Deprecated: Function is_integer() is deprecated, use is_int() instead
</blockquote>

==== Deprecate is_long() ====

  * Author: Jordi Kroon <jordikroon@me.com>

Following the [[rfc: deprecations_php_8_5#deprecate_non-standard_cast_names|deprecation of non standard cast names in PHP 8.5]], it is consistent to consider deprecating legacy aliases which preserve the same non canonical type terminology.

<php>is_long()</php> is a legacy alias of <php>is_int()</php>. The name originates from historical internal naming and platform specific integer sizing, but it no longer communicates anything useful to userland code.

Modern PHP presents the scalar type as <php>int</php>, and the canonical predicate is <php>is_int()</php>. Having <php>is_long()</php> as an additional alias offers no functional value and keeps outdated terminology alive.

This proposal deprecates <php>is_long()</php> and recommends using <php>is_int()</php> instead.

<PHP>
if (is_long($value)) {
    // ...
}
// To:
if (is_int($value)) {
    // ...
}
</PHP>

If accepted, calling <php>is_long()</php> will emit a deprecation notice:

<blockquote>
Deprecated: Function is_long() is deprecated, use is_int() instead
</blockquote>

==== Deprecate doubleval() ====

  * Author: Jordi Kroon <jordikroon@me.com>

Following the [[rfc: deprecations_php_8_5#deprecate_non-standard_cast_names|deprecation of non standard cast names in PHP 8.5]], it is consistent to consider <php>doubleval()</php> as well, as it reflects the same legacy terminology as the deprecated <php>(double)</php> cast.

<php>doubleval()</php> is a legacy alias of <php>floatval()</php>. Since <php>floatval()</php> is the canonical function name and matches the scalar type name <php>float</php>, keeping <php>doubleval()</php> provides no distinct behavior and only increases the number of ways to express the same conversion.

This proposal deprecates <php>doubleval()</php> and recommends using <php>floatval()</php> instead.

<PHP>
$number = doubleval($value);
// To:
$number = floatval($value);
</PHP>

If accepted, calling <php>doubleval()</php> will emit a deprecation notice:

<blockquote>
Deprecated: Function doubleval() is deprecated, use floatval() instead
</blockquote>

==== Deprecate returning a value from __construct() ====

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

TODO: See discussion in https://news-web.php.net/php.internals/129980

==== Deprecate mysqli_get_charset() ====

  * Author: Kamil Tekiela

This function can be used to retrieve internal implementation details of the currently selected character set. It was able to provide more meaningful values when mysqli was compiled against libmysql but since PHP 8.2 it's no longer the case. The values reported are:

  * Character set name. The same as is returned by <php>mysqli_character_set_name()</php>
  * Default collation name for that charset as defined by mysqlnd, not by the server. As this information doesn't correspond to the true values defined by the server it is of no use to anyone.
  * Directory from which the charset information was imported. Used only with libmysql for dynamically loaded character sets. In mysqlnd it's an empty string.
  * Minimum and maximum character length of the character set. This is the only truly useful and correct information provided by this function, but it is still an implementation detail and in my opinion, not something that a PHP user would ever need to know. 
  * Collation ID as defined by mysqlnd. It's just a number. It cannot be used for anything as it's not guaranteed that it's the same as defined in MySQL/MariaDB. As of PHP 8.6, it is set to 0 in all cases. Even in libmysql it's no longer used, other than for finding out the default collation of a charset for backwards compatibility reasons. 
  * State. In libmysql it is always the value 1. In libmysql it was a bitflag of internal characteristics of the character set. It has no use in PHP.

The proposal is to deprecate and remove this function, and its OO-style alias <php>mysqli::get_charset()</php>, and later remove it without a substitute. It's pretty unlikely that any PHP project still uses this function, and if they do, they probably don't know that it returns falsified information. The only uses I was able to find (see the user comment in PHP manual) are people incorrectly assuming that it returns the currently set collation. By removing this function, we reduce one more point of confusion for PHP users. 

If accepted, calling <php>mysqli_get_charset()</php> will emit a deprecation notice:

<blockquote>
Deprecated: Function mysqli_get_charset() is deprecated, did you mean mysqli_character_set_name()?
</blockquote>

The reason for this message is that <php>mysqli_get_charset</php> seems like a logical antonym to <php>mysqli_set_charset</php> and people wanting to know the name of currently selected character set should use <php>mysqli_character_set_name</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.