_deprecated_function( string $function_name, string $version, string $replacement )

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

Description

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.

Parameters

$function_namestringrequired
The function that was called.
$versionstringrequired
The version of WordPress that deprecated the function.
$replacementstringoptional
The function that should have been called. Default empty string.

Source

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 );
	}
}

Hooks

do_action( ‘deprecated_function_run’, string $function_name, string $replacement, string $version )

Fires when a deprecated function is called.

apply_filters( ‘deprecated_function_trigger_error’, bool $trigger )

Filters whether to trigger an error for deprecated functions.

Changelog

VersionDescription
5.4.0The error type is now classified as E_USER_DEPRECATED (used to default to E_USER_NOTICE).
2.5.0Introduced.

User Contributed Notes

  1. Skip to note 2 content

    Here’s an example showing how to deprecate an old function old_get_featured_image in favor of a new function get_featured_image_url

    /**
     * Retrieves the featured image URL (deprecated).
     *
     * @deprecated 2.0.0 Use get_featured_image_url() instead.
     *
     * @param int $post_id The post ID.
     * @return string|false The featured image URL or false if none.
     */
    function old_get_featured_image( $post_id ) {
        // Trigger a deprecation notice
        _deprecated_function( __FUNCTION__, '2.0.0', 'get_featured_image_url' );
    
        // Call the replacement function so old code still works
        return get_featured_image_url( $post_id );
    }
    
    /**
     * Replacement function for retrieving the featured image URL.
     *
     * @param int $post_id The post ID.
     * @return string|false The featured image URL or false if none.
     */
    function get_featured_image_url( $post_id ) {
        return get_the_post_thumbnail_url( $post_id );
    }

You must log in before being able to contribute a note or feedback.