_deprecated_function() │ WP 2.5.0

Mark a function as deprecated and inform when it has been used.

There is a deprecated_function_run hook 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.

Internal function — this function is designed to be used by the kernel itself. It is not recommended to use this function in your code.

Hooks from the function

Return

null. Nothing (null).

Usage

_deprecated_function( $function_name, $version, $replacement );
$function_name(string) (required)
The function that was called.
$version(string) (required)
The version of WordPress that deprecated the function.
$replacement(string)
The function that should have been called.
Default: empty string

Examples

0

#1 Example of use in the kernel 

function logIO( $io, $msg ) {
	_deprecated_function( __FUNCTION__, '3.4', 'error_log()' );

	if ( ! empty( $GLOBALS['xmlrpc_logging'] ) )
		error_log( $io . ' - ' . $msg );
}

Changelog

Since 2.5.0 Introduced.
Since 5.4.0 This function is no longer marked as "private".
Since 5.4.0 The error type is now classified as E_USER_DEPRECATED (used to default to E_USER_NOTICE).

_deprecated_function() code WP 6.5.2

wp-includes/functions.php 
function _deprecated_function( $function_name, $version, $replacement = '' ) {

	/**
	 * Fires when a deprecated function is called.
	 *
	 * @since 2.5.0
	 *
	 * @param string $function_name 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_name, $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 ) {
				$message = 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_name,
					$version,
					$replacement
				);
			} else {
				$message = 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_name,
					$version
				);
			}
		} else {
			if ( $replacement ) {
				$message = sprintf(
					'Function %1$s is <strong>deprecated</strong> since version %2$s! Use %3$s instead.',
					$function_name,
					$version,
					$replacement
				);
			} else {
				$message = sprintf(
					'Function %1$s is <strong>deprecated</strong> since version %2$s with no alternative available.',
					$function_name,
					$version
				);
			}
		}

		wp_trigger_error( '', $message, E_USER_DEPRECATED );
	}
}

WP core