_deprecated_function() │ WP 2.5.0

Outputs a message that the specified WP function is deprecated.

The function can be used in plugins/themes if you have deprecated functions that may no longer be used in future versions.

To output an error message, the constant WP_DEBUG in wp-config.php must be enabled (set to true).

The hook deprecated_function_run is needed when you need to do something upon calling a deprecated function, regardless of whether the constant WP_DEBUG is enabled or disabled. For example, you can use the function to log possible errors from calling deprecated (forbidden) functions somewhere in the log.

Works based on the basic PHP function trigger_error().

There is also a similar function: _deprecated_argument()

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

Returns

null.

Usage

_deprecated_function( $function, $version, $replacement );
$function(string) (required)
Name of the called function. Usually specified as __FUNCTION__ if the function is called from inside another function or __METHOD__ if from a class method.
$version(string) (required)
The version of WordPress from which the function is marked as deprecated.
$replacement(string)
The name of the function that should be used instead of the current one.
Default: null

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.9.1

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