_deprecated_class()
云策文档标注
概述
_deprecated_class() 函数用于标记一个类为已弃用，并在使用时通知开发者。它通常在类构造函数中调用，以处理弃用逻辑。
关键要点
- 函数触发 'deprecated_class_run' Hook，可用于获取调用弃用类的回溯信息。
- 当 WP_DEBUG 为 true 且 'deprecated_class_trigger_error' 过滤器允许时，会触发用户错误（E_USER_DEPRECATED）。
- 参数包括类名、弃用版本和可选的替代类或函数。
- 函数内部根据是否有替代项生成相应的弃用消息，支持国际化。
代码示例
function _deprecated_class( $class_name, $version, $replacement = '' ) {
do_action( 'deprecated_class_run', $class_name, $replacement, $version );
if ( WP_DEBUG && apply_filters( 'deprecated_class_trigger_error', true ) ) {
if ( function_exists( '__' ) ) {
if ( $replacement ) {
$message = sprintf(
__( 'Class %1$s is deprecated since version %2$s! Use %3$s instead.' ),
$class_name,
$version,
$replacement
);
} else {
$message = sprintf(
__( 'Class %1$s is deprecated since version %2$s with no alternative available.' ),
$class_name,
$version
);
}
} else {
if ( $replacement ) {
$message = sprintf(
'Class %1$s is deprecated since version %2$s! Use %3$s instead.',
$class_name,
$version,
$replacement
);
} else {
$message = sprintf(
'Class %1$s is deprecated since version %2$s with no alternative available.',
$class_name,
$version
);
}
}
wp_trigger_error( '', $message, E_USER_DEPRECATED );
}
}注意事项
- 此函数自 WordPress 6.4.0 版本引入。
- 弃用 PHP4 风格构造函数应使用 _deprecated_constructor() 函数。
- 相关函数包括 wp_trigger_error()、__()、do_action() 和 apply_filters()。
原文内容
Marks a class as deprecated and informs when it has been used.
Description
There is a ‘deprecated_class_run’ hook that will be called that can be used to get the backtrace up to what file and function called the deprecated class.
The current behavior is to trigger a user error if WP_DEBUG is true.
This function is to be used in the class constructor for every deprecated class.
See _deprecated_constructor() for deprecating PHP4-style constructors.
Parameters
$class_namestringrequired-
The name of the class being instantiated.
$versionstringrequired-
The version of WordPress that deprecated the class.
$replacementstringoptional-
The class or function that should have been called.
Default empty string.
Source
function _deprecated_class( $class_name, $version, $replacement = '' ) {
/**
* Fires when a deprecated class is called.
*
* @since 6.4.0
*
* @param string $class_name The name of the class being instantiated.
* @param string $replacement The class or function that should have been called.
* @param string $version The version of WordPress that deprecated the class.
*/
do_action( 'deprecated_class_run', $class_name, $replacement, $version );
/**
* Filters whether to trigger an error for a deprecated class.
*
* @since 6.4.0
*
* @param bool $trigger Whether to trigger an error for a deprecated class. Default true.
*/
if ( WP_DEBUG && apply_filters( 'deprecated_class_trigger_error', true ) ) {
if ( function_exists( '__' ) ) {
if ( $replacement ) {
$message = sprintf(
/* translators: 1: PHP class name, 2: Version number, 3: Alternative class or function name. */
__( 'Class %1$s is <strong>deprecated</strong> since version %2$s! Use %3$s instead.' ),
$class_name,
$version,
$replacement
);
} else {
$message = sprintf(
/* translators: 1: PHP class name, 2: Version number. */
__( 'Class %1$s is <strong>deprecated</strong> since version %2$s with no alternative available.' ),
$class_name,
$version
);
}
} else {
if ( $replacement ) {
$message = sprintf(
'Class %1$s is <strong>deprecated</strong> since version %2$s! Use %3$s instead.',
$class_name,
$version,
$replacement
);
} else {
$message = sprintf(
'Class %1$s is <strong>deprecated</strong> since version %2$s with no alternative available.',
$class_name,
$version
);
}
}
wp_trigger_error( '', $message, E_USER_DEPRECATED );
}
}
Hooks
- do_action( ‘deprecated_class_run’, string $class_name, string $replacement, string $version )
-
Fires when a deprecated class is called.
- apply_filters( ‘deprecated_class_trigger_error’, bool $trigger )
-
Filters whether to trigger an error for a deprecated class.
Changelog
| Version | Description |
|---|---|
| 6.4.0 | Introduced. |