Rendering a PHP function deprecated

To deprecate a function in WordPress, you can use the trigger_error function to issue a warning and inform developers that the function should no longer be used. In addition, you can provide a recommended alternative and indicate the version from which the function is deprecated.

Steps to make a function deprecated

Add depreciation warning: Use trigger_error to generate a warning when an deprecated function is called.
Specify alternative: Provide a suggestion for an alternative function or updated method.
Documentation: Document in the code the version from which the function is deprecated and why.

Example

Suppose you have a function called my_old_function that you want to make deprecated.

PHP

<?php
if (!function_exists('my_old_function')) {
    /**
     * My Old Function
     *
     * @deprecated 1.0.0 Use my_new_function() instead.
     */
    function my_old_function() {
        // Get the backtrace
        $backtrace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2);
        $caller = isset($backtrace[1]['function']) ? $backtrace[1]['function'] : 'global scope';
        $file = isset($backtrace[0]['file']) ? $backtrace[0]['file'] : 'unknown file';
        $line = isset($backtrace[0]['line']) ? $backtrace[0]['line'] : 'unknown line';

        // Generate a deprecated notice with caller information
        trigger_error(
            sprintf(
                __('%1$s is deprecated since version %2$s! Use %3$s instead. Called by %4$s in %5$s on line %6$s.', 'text-domain'),
                'my_old_function()',
                '1.0.0',
                'my_new_function()',
                $caller,
                $file,
                $line
            ),
            E_USER_DEPRECATED
        );

        // Call the new function as a fallback
        my_new_function();
    }
}

/**
 * My New Function
 *
 * This is the new function that should be used instead of my_old_function.
 */
function my_new_function() {
    // Code de la nouvelle fonction
}
?>

Explanation

if (!function_exists('my_old_function')) { … }: This ensures that the function is only defined if it hasn’t already been defined, which is useful for avoiding redefinitions when using hooks or multiple themes/plugins.
trigger_error: This function generates an E_USER_DEPRECATED error, indicating that the function is obsolete. The message includes the name of the obsolete function, the version from which it is obsolete, and the recommended replacement function.
my_new_function(): This function represents the new recommended method that developers should use instead of the old one.
debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2): This function retrieves the call stack, ignoring function arguments to simplify results. The second argument 2 limits the depth of the trace to two levels: the current level and the direct caller.
$caller: This variable contains the name of the function that called the obsolete function. If no function was found (for example, if the call was made from the global namespace), it returns global scope.
$file and $line: These variables contain the file and line where the obsolete function was called.

Use of a hook to handle deprecated errors (optional)

To capture and manage these warnings in WordPress administration, you can add a hook to display warning messages:

PHP

<?php
add_action('deprecated_function_run', function ($function, $replacement, $version) {
    if (WP_DEBUG) {
        // Affiche un message d'avertissement dans l'administration
        echo sprintf(
            '<div class="notice notice-warning"><p>%1$s is deprecated since version %2$s! Use %3$s instead.</p></div>',
            $function,
            $version,
            $replacement
        );
    }
}, 10, 3);
?>

Deprecating a PHP function

Steps to make a function deprecated

Example

Explanation

Use of a hook to handle deprecated errors (optional)