_deprecated_constructor()
云策文档标注
概述
_deprecated_constructor() 函数用于标记 PHP4 风格的构造函数为已弃用，并在使用时触发通知。它类似于 _deprecated_function()，但针对构造函数场景，主要用于移除旧版 PHP4 风格的构造函数。
关键要点
- 函数作用：标记构造函数为已弃用，当 WP_DEBUG 为 true 时触发用户错误，以帮助开发者迁移到 PHP5+ 的 __construct() 方法。
- 参数说明：接受三个参数：$class_name（包含弃用构造函数的类名，必需）、$version（WordPress 弃用该构造函数的版本，必需）、$parent_class（调用弃用构造函数的父类名，可选，默认为空字符串）。
- 触发机制：通过 do_action('deprecated_constructor_run', ...) 触发动作，并基于 WP_DEBUG 和 apply_filters('deprecated_constructor_trigger_error', true) 过滤器决定是否生成错误消息。
- 错误消息：根据是否有 $parent_class 参数，生成不同的本地化或英文消息，提示使用 __construct() 替代。
- 相关钩子：包括 deprecated_constructor_run 动作和 deprecated_constructor_trigger_error 过滤器，用于自定义行为。
- 版本变更：自 WordPress 4.3.0 引入，4.5.0 添加 $parent_class 参数，5.4.0 将错误类型从 E_USER_NOTICE 改为 E_USER_DEPRECATED。
代码示例
function _deprecated_constructor( $class_name, $version, $parent_class = '' ) {
do_action( 'deprecated_constructor_run', $class_name, $version, $parent_class );
if ( WP_DEBUG && apply_filters( 'deprecated_constructor_trigger_error', true ) ) {
if ( function_exists( '__' ) ) {
if ( $parent_class ) {
$message = sprintf(
__( 'The called constructor method for %1$s class in %2$s is deprecated since version %3$s! Use %4$s instead.' ),
$class_name,
$parent_class,
$version,
'__construct()'
);
} else {
$message = sprintf(
__( 'The called constructor method for %1$s class is deprecated since version %2$s! Use %3$s instead.' ),
$class_name,
$version,
'__construct()'
);
}
} else {
// 非本地化消息类似
}
wp_trigger_error( '', $message, E_USER_DEPRECATED );
}
}注意事项
- 此函数应仅用于 PHP4 风格的构造函数（即与类同名的方法），以促进代码现代化。
- 错误触发依赖于 WP_DEBUG 常量设置为 true，确保在生产环境中不会意外显示错误。
- 使用过滤器 deprecated_constructor_trigger_error 可以控制是否触发错误，提供灵活性。
- 消息支持本地化，通过 __() 函数处理，增强国际化支持。
原文内容
Marks a constructor as deprecated and informs when it has been used.
Description
Similar to _deprecated_function() , but with different strings. Used to remove PHP4-style constructors.
The current behavior is to trigger a user error if WP_DEBUG is true.
This function is to be used in every PHP4-style constructor method that is deprecated.
Parameters
$class_namestringrequired-
The class containing the deprecated constructor.
$versionstringrequired-
The version of WordPress that deprecated the function.
$parent_classstringoptional-
The parent class calling the deprecated constructor.
Default empty string.
Source
function _deprecated_constructor( $class_name, $version, $parent_class = '' ) {
/**
* Fires when a deprecated constructor is called.
*
* @since 4.3.0
* @since 4.5.0 Added the `$parent_class` parameter.
*
* @param string $class_name The class containing the deprecated constructor.
* @param string $version The version of WordPress that deprecated the function.
* @param string $parent_class The parent class calling the deprecated constructor.
*/
do_action( 'deprecated_constructor_run', $class_name, $version, $parent_class );
/**
* Filters whether to trigger an error for deprecated functions.
*
* `WP_DEBUG` must be true in addition to the filter evaluating to true.
*
* @since 4.3.0
*
* @param bool $trigger Whether to trigger the error for deprecated functions. Default true.
*/
if ( WP_DEBUG && apply_filters( 'deprecated_constructor_trigger_error', true ) ) {
if ( function_exists( '__' ) ) {
if ( $parent_class ) {
$message = sprintf(
/* translators: 1: PHP class name, 2: PHP parent class name, 3: Version number, 4: __construct() method. */
__( 'The called constructor method for %1$s class in %2$s is <strong>deprecated</strong> since version %3$s! Use %4$s instead.' ),
$class_name,
$parent_class,
$version,
'<code>__construct()</code>'
);
} else {
$message = sprintf(
/* translators: 1: PHP class name, 2: Version number, 3: __construct() method. */
__( 'The called constructor method for %1$s class is <strong>deprecated</strong> since version %2$s! Use %3$s instead.' ),
$class_name,
$version,
'<code>__construct()</code>'
);
}
} else {
if ( $parent_class ) {
$message = sprintf(
'The called constructor method for %1$s class in %2$s is <strong>deprecated</strong> since version %3$s! Use %4$s instead.',
$class_name,
$parent_class,
$version,
'<code>__construct()</code>'
);
} else {
$message = sprintf(
'The called constructor method for %1$s class is <strong>deprecated</strong> since version %2$s! Use %3$s instead.',
$class_name,
$version,
'<code>__construct()</code>'
);
}
}
wp_trigger_error( '', $message, E_USER_DEPRECATED );
}
}
Hooks
- do_action( ‘deprecated_constructor_run’, string $class_name, string $version, string $parent_class )
-
Fires when a deprecated constructor is called.
- apply_filters( ‘deprecated_constructor_trigger_error’, bool $trigger )
-
Filters whether to trigger an error for deprecated functions.