What is E_DEPRECATED in PHP, and how to handle it in WordPress

What E_DEPRECATED is

PHP sorts its messages into levels, each a constant with a number. php.net describes E_DEPRECATED as: “Run-time deprecation notices. Enable this to receive warnings about code that will not work in future versions.” (php.net)

So a deprecation notice is PHP saying: this still works, but plan for the day it won’t. Every PHP version deprecates a few things, and a later version removes some of them. PHP 8.0, for example, removed functions that 7.2 to 7.4 had deprecated, such as create_function() (the list).

The levels you’ll meet in WordPress

php.net on the user-level twin: “User-generated deprecation message. This is like an E_DEPRECATED, except it is generated in PHP code by using the PHP function trigger_error().” And on E_ALL, whose value it gives as 30719: “Prior to PHP 8.4, the constant value was: 32767” (php.net). We checked both values on the official PHP 7.4, 8.0, 8.4 and 8.5 builds. More on the level PHP 8.4 dropped: “Constant E_STRICT is deprecated”.

Both kinds, and how they’re filtered

A plugin calls utf8_encode(), deprecated by PHP 8.2 (E_DEPRECATED), and one of its own old functions announces itself the way WordPress does (E_USER_DEPRECATED). Reported with E_ALL, both show; with both levels left out, neither does, and the code runs the same:

<?php
// Every message level reported (what WP_DEBUG does):
error_reporting(E_ALL);
echo utf8_encode('Caf'), "\n";
trigger_error('Function old_import() is deprecated since version 2.0!', E_USER_DEPRECATED);

// Deprecation messages left out (what WordPress does while WP_DEBUG is off):
error_reporting(E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED);
echo utf8_encode('Caf'), "\n";
trigger_error('Function old_import() is deprecated since version 2.0!', E_USER_DEPRECATED);
echo "Done\n";

Deprecated: Function utf8_encode() is deprecated in /var/www/html/wp-content/plugins/old-importer/import.php on line 4
Caf

Deprecated: Function old_import() is deprecated since version 2.0! in /var/www/html/wp-content/plugins/old-importer/import.php on line 5
Caf
Done

Deprecated: Function utf8_encode() is deprecated since 8.2, visit the php.net documentation for various alternatives in /var/www/html/wp-content/plugins/old-importer/import.php on line 4
Caf

Deprecated: Function old_import() is deprecated since version 2.0! in /var/www/html/wp-content/plugins/old-importer/import.php on line 5
Caf
Done

How WordPress handles them

WordPress sets PHP’s error level itself, depending on WP_DEBUG (WordPress 7.1.2 source):

• WP_DEBUG on: E_ALL, every level, deprecation notices included.
• WP_DEBUG off: a list of levels without notices and without either deprecation level:

error_reporting( E_CORE_ERROR | E_CORE_WARNING | E_COMPILE_ERROR | E_ERROR | E_WARNING | E_PARSE | E_USER_ERROR | E_USER_WARNING | E_RECOVERABLE_ERROR );

WordPress’s own outdated functions announce themselves with E_USER_DEPRECATED, and only while WP_DEBUG is on and the deprecated_function_trigger_error filter allows it (WordPress 7.1.2 source). Their message names a WordPress version, not a PHP version.

How to handle them

For what each level does to a page, with examples: deprecation notice or fatal error.

Find them before the next PHP version

The deprecations a PHP upgrade brings are in your plugins’ code before you switch. CompatNav, a free plugin on wordpress.org, lists them per plugin and theme for the PHP version you choose (8.0 to 8.5), labelled “Deprecation notice”, separately from what will break: