WordPress 教程:函数和接口被弃用之后,怎么操作?

WordPress 插件升级,可能一些函数,方法,参数,接口,甚至文件被弃用了,但是其他开发者使用这些函数,方法或者接口,如何提示,并且代码兼容呢,WordPress 提供了这些方法:

弃用接口

弃用 filter hook

apply_filters_deprecated( $tag, $args, $version, $replacement = false, $message = null )

如果要弃用一个 filter hook,请使用 apply_filters_deprecated 代替 apply_filtersapply_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 hook

do_action_deprecated( $tag, $args, $version, $replacement = false, $message = null )

这个和 apply_filters_deprecated 一样,只是它是用来弃用 action hook 的,一样也是使用 do_action_deprecated 代替 do_actiondo_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 = '' )

这个用到概率会很少很少,这里不讲解了,建议用到的时候直接查源代码和例子使用。

标签: WordPress 教程

热门文章