Mark a function as deprecated and inform when it has been used.
There is a hook deprecated_function_run that will be called that can be used to get the backtrace up to what file and function called the deprecated function.
The current behavior is to trigger a user error if WP_DEBUG is true.
This function is to be used in every function that is deprecated.
This is an internal function for using it by WP core itself. It's not recommended to use this function in your code.
function _deprecated_function( $function, $version, $replacement = '' ) {
/**
* Fires when a deprecated function is called.
*
* @since 2.5.0
*
* @param string $function The function that was called.
* @param string $replacement The function that should have been called.
* @param string $version The version of WordPress that deprecated the function.
*/
do_action( 'deprecated_function_run', $function, $replacement, $version );
/**
* Filters whether to trigger an error for deprecated functions.
*
* @since 2.5.0
*
* @param bool $trigger Whether to trigger the error for deprecated functions. Default true.
*/
if ( WP_DEBUG && apply_filters( 'deprecated_function_trigger_error', true ) ) {
if ( function_exists( '__' ) ) {
if ( $replacement ) {
trigger_error(
sprintf(
/* translators: 1: PHP function name, 2: Version number, 3: Alternative function name. */
__( 'Function %1$s is <strong>deprecated</strong> since version %2$s! Use %3$s instead.' ),
$function,
$version,
$replacement
),
E_USER_DEPRECATED
);
} else {
trigger_error(
sprintf(
/* translators: 1: PHP function name, 2: Version number. */
__( 'Function %1$s is <strong>deprecated</strong> since version %2$s with no alternative available.' ),
$function,
$version
),
E_USER_DEPRECATED
);
}
} else {
if ( $replacement ) {
trigger_error(
sprintf(
'Function %1$s is <strong>deprecated</strong> since version %2$s! Use %3$s instead.',
$function,
$version,
$replacement
),
E_USER_DEPRECATED
);
} else {
trigger_error(
sprintf(
'Function %1$s is <strong>deprecated</strong> since version %2$s with no alternative available.',
$function,
$version
),
E_USER_DEPRECATED
);
}
}
}
}