WordPress 教程:函数和接口被弃用之后,怎么提示?
WordPress 升级,可能会弃用一些函数,方法,参数,接口,甚至文件,虽然这些函数、方法和接口等都还会保留,但是需要提示用到这些开发者,已经被弃用,要使用新的函数、方法和接口等了。
WordPress 提供了下面这些函数来提示开发者,作为插件开发者,如果在弃用自己的插件中的一些函数、方法和接口的时候,也可以使用 WordPress 这些弃用提示方法。
弃用 Filter 接口
apply_filters_deprecated( $tag, $args, $version, $replacement = false, $message = null )
如果要弃用一个 filter hook,请使用 apply_filters_deprecated
代替 apply_filters
,apply_filters_deprecated
会触发一个该 filter hook 被弃用的通知,然后调用原来的 filter hook。
比如 WPJAM Basic 插件里面的 wpjam_post_thumbnail_uri
的接口放弃不再使用了,为了兼容:
那么原来的代码:
$thumbnail_url = apply_filters('wpjam_post_thumbnail_uri', $thumbnail_url, $post);
可以改成:
$thumbnail_url = apply_filters_deprecated('wpjam_post_thumbnail_uri', [$thumbnail_url, $post], 'WPJAM Basic 3.2', 'wpjam_post_thumbnail_url');
这样就能保证 wpjam_post_thumbnail_uri
还有用,兼容现有的程序,但是如果主题里面调用该函数,就是在 log 里面看到:
自WPJAM Basic 3.2版本起,已不建议使用wpjam_post_thumbnail_uri,请换用wpjam_post_thumbnail_url。
这样就可以根据提示进行修改了。
apply_filters_deprecated
五个参数:
- 要放弃的 filter hook。
- 原来 filter hook 的参数。
- 开始弃用该 filter hook 的版本号。
- 用来替换的新 filter hook,可以为空,就是彻底放弃。
- 给开发者的一段描述消息。
弃用 action 接口
do_action_deprecated( $tag, $args, $version, $replacement = false, $message = null )
这个和 apply_filters_deprecated
一样,只是它是用来弃用 action hook 的,一样也是使用 do_action_deprecated
代替 do_action
,do_action_deprecated
会触发一个该 filter action 被弃用的通知,然后调用原来的 action hook。
用法和 apply_filters_deprecated
一致,不再举例,参数也差不多:
- 要放弃的 action hook。
- 原来 action hook 的参数。
- 开始弃用该 action hook 的版本号。
- 用来替换的新 action hook,可以为空,就是彻底放弃。
- 给开发者的一段描述消息。
弃用函数和方法
_deprecated_function( $function, $version, $replacement = null )
这个 WordPress 内置的方法可以把一个函数设置为弃用的,并且再被使用的时候通知用户。
比如我原先写了一个函数 wpjam_is_mobile
用来判断当前环境是不是在浏览器中,后来发现 WordPress 内置的 wp_is_mobile
一模一样,所以就可以弃用他:
function wpjam_is_mobile() {
_deprecated_function(__FUNCTION__, 'WPJAM Basic 3.2', 'wp_is_mobile');
return wp_is_mobile();
}
_deprecated_function
有三个参数:
- 要放弃的函数,如果弃用的是函数,可以使用魔术变量
__FUNCTION__
,如果是类的方法,可以使用魔术变量__METHOD__
, - 开始弃用该函数的版本号。
- 用来替换的新函数,可以为空,就是彻底放弃。
弃用参数
_deprecated_argument( $function, $version, $message = null )
比如 WP_Query
弃用 caller_get_posts
参数,就可以这样处理:
if ( isset( $q['caller_get_posts'] ) ) {
_deprecated_argument( 'WP_Query', '3.1.0', '<code>caller_get_posts</code>已经弃用,请使用<code>ignore_sticky_posts</code>代替');
if ( ! isset( $q['ignore_sticky_posts'] ) ) {
$q['ignore_sticky_posts'] = $q['caller_get_posts'];
}
}
_deprecated_argument
有三个参数:
- 要放弃参数的函数或者类,同样可以使用魔术变量。
- 开始弃用该参数的版本号。
- 给开发者的一段描述消息。
弃用文件和类的构建函数
_deprecated_file( $file, $version, $replacement = null, $message = '' )
_deprecated_constructor( $class, $version, $parent_class = '' )
这个用到概率会会很少,这里不讲解了,建议用到的时候直接查看源代码和例子使用。