rfc:deprecations_php_7_3

This is an old revision of the document!


PHP RFC: Deprecations for PHP 7.3

Introduction

This is a draft RFC for multiple deprecations targeting PHP 7.3. The RFC proposes to deprecate the listed functionality in PHP 7.3 and remove it in PHP 8.

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

  • Undocumented mbstring function aliases
  • String search functions with integer needle
  • fgetss() function and string.strip_tags filter
  • Defining a free-standing assert() function
  • FILTER_FLAG_SCHEME_REQUIRED and FILTER_FLAG_HOST_REQUIRED flags
  • FILTER_SANITIZE_MAGIC_QUOTES filter
  • pdo_odbc.db2_instance_name php.ini directive

Proposal

Each feature proposed for deprecation is voted separately. Each vote requires a 2/3 majority, independently of whether it is a language or standard library change. All votes refer to deprecation in PHP 7.3 and removal in the next major version (presumably PHP 8.0).

Undocumented mbstring function aliases

The functions mbregex_encoding, mbereg, mberegi, mbereg_replace, mberegi_replace, mbsplit, mbereg_match, mbereg_search, mbereg_search_pos, mbereg_search_regs, mbereg_search_init, mbereg_search_getregs, mbereg_search_getpos and mbereg_search_setpos are undocumented aliases of the same functions using an mb_ prefix (e.g., mb_ereg).

Proposed action: Mark the functions as deprecated, so that a deprecation notice is emitted on every call. In PHP 8 these aliases will be removed.

String search functions with integer needle

The following applies to the strpos, strrpos, stripos, strripos, strstr, strchr, strrchr and stristr functions. strpos will be used as a representative example.

String search functions usually operate on a string needle. However, if a non-string is passed, it will be converted to an integer and interpreted as an ASCII codepoint:

$str = "There are 10 apples";
var_dump(strpos($str, "10")); // int(10)
var_dump(strpos($str, 10));   // bool(false)

In a language that relies on transparent type juggling between scalar types, this is problemantic, because the type can easily change depending on the used data source. For example, array keys in PHP are automatically converted to integers, so that using an array key as a strpos needle may not work correctly, because it is interpreted as an ASCII codepoint rather than a string.

Proposed action: Throw a deprecation warning if a non-string is passed as a needle to strpos or one of the above-listed functions. The deprecation warning should note that an explicit chr call may be used instead. In PHP 8 the deprecation warning will be removed and the needle parameter will be changed into a string.

fgetss() function and string.strip_tags filter

The fgetss() function and the string.strip_tags stream filters expose the functionality of strip_tags() in a streaming matter. The need to support these makes the implementation of strip_tags() more complicated, as a streaming state machine is necessary. On the other hand, these functions seem to be of very little utility. strip_tags() itself, due to its limitations and known bugs, already has very few legitimate applications. There is no need to provide native support for streaming application on top of that.

Proposed action: Mark fgetss(), gzgetss() and SplFileObject::fgetss() as deprecated, so that a deprecation notice is emitted on every call. Generate a deprecation notice if the string.strip_tags stream filter is created. In PHP 8 the functions and the stream filter are removed.

Defining a free-standing assert() function

Since PHP 7.0 the assert() function is subject to special treatment in the compiler. In particular, calls to assert() will be elided if zend.assertions=-1 is set. To make this elision of asserts in production systems work reliably, this also applies to unqualified assert() calls inside namespaces. However, such calls may refer to a namespaced variant of assert() rather than the global function, and such calls are thus also subjected to zend.assertions=-1. See Bug #75445.

To avoid confusion due to this behavior, it is suggested to forbid the definition of free-standing assert() functions. Methods are unaffected.

Proposed action: Generate a compile-time deprecation warning if an assert() function is declared. In PHP 8 this becomes a compile-error.

FILTER_FLAG_SCHEME_REQUIRED and FILTER_FLAG_HOST_REQUIRED

As of PHP 5.2.1 FILTER_VALIDATE_URL implies FILTER_FLAG_SCHEME_REQUIRED and FILTER_FLAG_HOST_REQUIRED. Not only are these constants useless, they also create the incorrect impression that the scheme/host requirement can be disabled.

Proposed action: Generate a deprecation warning if the FILTER_FLAG_SCHEME_REQUIRED or FILTER_FLAG_HOST_REQUIRED flags are explicitly set in calls to filter APIs (PHP currently has no mechanism to deprecate the constants themselves). In PHP 8 the constants will be removed.

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

FILTER_SANITIZE_MAGIC_QUOTES

Magic quotes were deprecated all the way back in PHP 5.3 and later removed in PHP 5.4, however FILTER_SANITIZE_MAGIC_QUOTES was never deprecated. This filter basically mimics calling addslashes() on the input in question.

Proposed action: Emit a deprecation notice each time the FILTER_SANITIZE_MAGIC_QUOTES filter is used.

pdo_odbc.db2_instance_name php.ini directive

As of PHP 5.1.1 pdo_odbc.db2_instance_name was marked as deprecated in the manual, promising removal in a future version of PHP. This ini directive modifies the DB2INSTANCE environment variable for non Windows operating systems, allowing pdo_odbc to make cataloged connections to a DB2 database.

The side effect here is that this setting is process wide and also affects the ODBC extension, which can create some hard to debug situations. Besides this, the PECL package, ibm_db2 seems to implement the exact same behavior which could also conflict.

Proposed action: Add a deprecation notice if the ini directive has a value at module initialization.

Implementations: https://gist.github.com/KalleZ/424ea78492cd5f4c2198cba6b25403d9

Backward Incompatible Changes

For PHP 7.3 additional deprecation notices will appear. For PHP 8.0 the previously deprecated functionality will no longer be available.

Vote

Each of the bullet points above will get a separate vote. All votes will require a 2/3 supermajority, independently of whether they are language changes or not.

rfc/deprecations_php_7_3.1530821519.txt.gz · Last modified: 2018/07/05 20:11 by nikic