函数文档

_deprecated_function()

💡 云策文档标注

概述

_deprecated_function() 是 WordPress 中用于标记函数已弃用的核心函数,当被调用时会触发通知,帮助开发者迁移到新函数。它主要用于在 WP_DEBUG 启用时生成用户错误,并提供了钩子用于跟踪调用来源。

关键要点

  • 函数作用:标记函数为弃用状态,并在使用时通过触发错误或通知来提醒开发者。
  • 触发条件:当 WP_DEBUG 为 true 且 deprecated_function_trigger_error 过滤器返回 true 时,会生成 E_USER_DEPRECATED 错误。
  • 参数说明:接受三个参数:$function_name(被调用的函数名)、$version(弃用该函数的 WordPress 版本)、$replacement(可选,替代函数名)。
  • 钩子支持:提供 deprecated_function_run 动作钩子,用于在弃用函数被调用时执行自定义逻辑;deprecated_function_trigger_error 过滤器钩子,用于控制是否触发错误。
  • 使用场景:应在所有弃用函数中调用此函数,以确保向后兼容性和平滑迁移。

代码示例

function old_get_featured_image( $post_id ) {
    _deprecated_function( __FUNCTION__, '2.0.0', 'get_featured_image_url' );
    return get_featured_image_url( $post_id );
}

注意事项

  • 从 WordPress 5.4.0 开始,错误类型从 E_USER_NOTICE 更改为 E_USER_DEPRECATED,提高了错误的严重性。
  • 此函数自 WordPress 2.5.0 引入,是处理函数弃用的标准方法。

📄 原文内容

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

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

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