_deprecated_file()
云策文档标注
概述
_deprecated_file() 函数用于标记一个文件为已弃用，并在该文件被包含时通知开发者。它通过触发钩子和错误消息来帮助迁移到新版本。
关键要点
- 函数用于标记已弃用的文件，当文件被包含时，会触发 'deprecated_file_included' 钩子，可用于获取调用栈信息。
- 在 WP_DEBUG 为 true 且 'deprecated_file_trigger_error' 过滤器允许时，会触发 E_USER_DEPRECATED 错误，显示弃用消息。
- 参数包括 $file（文件路径）、$version（弃用版本）、$replacement（替代文件，可选）和 $message（附加消息，可选）。
- 函数内部使用 do_action() 和 apply_filters() 来支持钩子，并调用 wp_trigger_error() 生成错误消息。
- 从 WordPress 5.4.0 开始，错误类型从 E_USER_NOTICE 改为 E_USER_DEPRECATED。
代码示例
function _deprecated_file( $file, $version, $replacement = '', $message = '' ) {
do_action( 'deprecated_file_included', $file, $replacement, $version, $message );
if ( WP_DEBUG && apply_filters( 'deprecated_file_trigger_error', true ) ) {
// 生成错误消息逻辑
wp_trigger_error( '', $message, E_USER_DEPRECATED );
}
}注意事项
- 此函数应在每个已弃用的文件中使用，以确保弃用通知能被正确触发。
- 错误触发依赖于 WP_DEBUG 设置和 'deprecated_file_trigger_error' 过滤器，开发者可通过过滤器控制是否显示错误。
- 消息支持国际化，使用 __() 函数进行翻译，但如果没有加载翻译函数，则使用英文默认消息。
原文内容
Marks a file as deprecated and inform when it has been used.
Description
There is a ‘deprecated_file_included’ hook that will be called that can be used to get the backtrace up to what file and function included the deprecated file.
The current behavior is to trigger a user error if WP_DEBUG is true.
This function is to be used in every file that is deprecated.
Parameters
$filestringrequired-
The file that was included.
$versionstringrequired-
The version of WordPress that deprecated the file.
$replacementstringoptional-
The file that should have been included based on ABSPATH.
Default empty string. $messagestringoptional-
A message regarding the change. Default empty string.
Source
function _deprecated_file( $file, $version, $replacement = '', $message = '' ) {
/**
* Fires when a deprecated file is called.
*
* @since 2.5.0
*
* @param string $file The file that was called.
* @param string $replacement The file that should have been included based on ABSPATH.
* @param string $version The version of WordPress that deprecated the file.
* @param string $message A message regarding the change.
*/
do_action( 'deprecated_file_included', $file, $replacement, $version, $message );
/**
* Filters whether to trigger an error for deprecated files.
*
* @since 2.5.0
*
* @param bool $trigger Whether to trigger the error for deprecated files. Default true.
*/
if ( WP_DEBUG && apply_filters( 'deprecated_file_trigger_error', true ) ) {
$message = empty( $message ) ? '' : ' ' . $message;
if ( function_exists( '__' ) ) {
if ( $replacement ) {
$message = sprintf(
/* translators: 1: PHP file name, 2: Version number, 3: Alternative file name. */
__( 'File %1$s is <strong>deprecated</strong> since version %2$s! Use %3$s instead.' ),
$file,
$version,
$replacement
) . $message;
} else {
$message = sprintf(
/* translators: 1: PHP file name, 2: Version number. */
__( 'File %1$s is <strong>deprecated</strong> since version %2$s with no alternative available.' ),
$file,
$version
) . $message;
}
} else {
if ( $replacement ) {
$message = sprintf(
'File %1$s is <strong>deprecated</strong> since version %2$s! Use %3$s instead.',
$file,
$version,
$replacement
);
} else {
$message = sprintf(
'File %1$s is <strong>deprecated</strong> since version %2$s with no alternative available.',
$file,
$version
) . $message;
}
}
wp_trigger_error( '', $message, E_USER_DEPRECATED );
}
}
Hooks
- do_action( ‘deprecated_file_included’, string $file, string $replacement, string $version, string $message )
-
Fires when a deprecated file is called.
- apply_filters( ‘deprecated_file_trigger_error’, bool $trigger )
-
Filters whether to trigger an error for deprecated files.