apply_filters_deprecated()
云策文档标注
概述
apply_filters_deprecated() 函数用于触发已弃用的过滤器钩子，替代 apply_filters() 调用，并生成弃用通知。它确保向后兼容性，同时引导开发者迁移到新钩子。
关键要点
- 当过滤器钩子被弃用时，应使用 apply_filters_deprecated() 替代 apply_filters()，以触发弃用通知并执行原始钩子。
- 参数 $args 必须是一个数组，包含传递给原始 apply_filters() 的所有值，例如 $value 和 $extra_arg。
- 函数内部检查钩子是否存在，若不存在则直接返回 $args[0]；否则调用 _deprecated_hook() 并应用 apply_filters_ref_array()。
- 相关函数包括 _deprecated_hook()、has_filter() 和 apply_filters_ref_array()，用于处理弃用逻辑和过滤器应用。
代码示例
// Old filter.
return apply_filters( 'wpdocs_filter', $value, $extra_arg );
// Deprecated.
return apply_filters_deprecated( 'wpdocs_filter', array( $value, $extra_arg ), '4.9.0', 'wpdocs_new_filter' );注意事项
- 确保 $args 参数正确传递所有原始参数，以避免数据丢失或错误。
- 弃用通知有助于开发者识别并更新代码到新钩子，提高代码维护性。
原文内容
Fires functions attached to a deprecated filter hook.
Description
When a filter hook is deprecated, the apply_filters() call is replaced with apply_filters_deprecated() , which triggers a deprecation notice and then fires the original filter hook.
Note: the value and extra arguments passed to the original apply_filters() call must be passed here to $args as an array. For example:
// Old filter.
return apply_filters( 'wpdocs_filter', $value, $extra_arg );
// Deprecated.
return apply_filters_deprecated( 'wpdocs_filter', array( $value, $extra_arg ), '4.9.0', 'wpdocs_new_filter' );See also
Parameters
$hook_namestringrequired-
The name of the filter hook.
$argsarrayrequired-
Array of additional function arguments to be passed to apply_filters() .
More Arguments from apply_filters( … $args )
Additional parameters to pass to the callback functions.
$versionstringrequired-
The version of WordPress that deprecated the hook.
$replacementstringoptional-
The hook that should have been used. Default empty.
$messagestringoptional-
A message regarding the change. Default empty.
Source
function apply_filters_deprecated( $hook_name, $args, $version, $replacement = '', $message = '' ) {
if ( ! has_filter( $hook_name ) ) {
return $args[0];
}
_deprecated_hook( $hook_name, $version, $replacement, $message );
return apply_filters_ref_array( $hook_name, $args );
}
Changelog
| Version | Description |
|---|---|
| 4.6.0 | Introduced. |