WordPress Plugin API（插件接口）

简介

本文介绍的是一些为 WordPress 插件开发者提供的 API (编程语言接口)，以及如何调用这些接口。

阅读本文之前，请先参考开发一个插件，以便了解一些关于插件的概况和详情。文本着重于“执行挂勾”类的接口，这类接口也被称为“过滤器”(Filters)和“动作”(Actions)，WordPress 正是使用这种接口把插件挂接到系统中的。

执行挂钩、动作和过滤器

WordPress 中有一种叫执行挂勾的机制，允许插件把一些功能“挂载”到 WordPress 当中。也就是说，在系统运行至某一个环节时，去调用插件内的一些函数。执行挂勾分为两种：

动作 (Action)： 动作是 WordPress 运行到某些环节，或者在某些事件发生时，就会被执行的一种挂钩。任何的插件都可以通过动作接口来指示系统在遇到这些环节或者事件的时候，就执行指定的 PHP 函数。

过滤器 (Filter)：过滤器的是 WordPress 用于修改即将要保存或者发送出去的数据的一种挂钩。任何的插件都可以通过过滤器接口来指示系统在遇到某些环节或者事件的时候，就执行指定的 PHP 函数去修改特定的数据。

某些时候动作或过滤器可以达到相同的效果。比如要修改文章的内容，可以把插件挂载到动作 publish_post 上，在文章的内容保存到数据库前就修改它。也可以把插件挂载到过滤器 the_content 上，在文章的内容发送到浏览器前修改它。

如果要查询 WordPress 中所有的标准的动作和插件，请参考： Adam Brown 的 WordPress 执行挂勾数据库。

函数参考

过滤器函数

• has_filter()
• add_filter()
• apply_filters()
• apply_filters_ref_array()
• current_filter()
• merge_filters()
• remove_filter()
• remove_all_filters()

动作函数

• has_action()
• add_action()
• do_action()
• do_action_ref_array()
• did_action()
• remove_action()
• remove_all_actions()

启用/禁用/卸载的函数

• register_activation_hook()
• register_uninstall_hook()
• register_deactivation_hook()

动作

动作 (Actions) 是由 WordPress 内部的某些事件所触发的，比如说发表一篇文章、更换主题或者访问后台的某个管理界面，这些都是一件事件的例子。而插件则可以指定某些 PHP 函数来响应这些事件所触发的动作。例如：

• 修改数据库数据
• 发送电子邮件
• 修改即将显示出来的内容

使用动作来挂载插件的基本步骤如下：

• 在插件代码中定义当某个事件发生时，需要执行的 PHP 函数
• 用add_action() 把这个函数注册到动作执行挂勾上
• 把插件源码放到 WordPress 指定的地方，然后启用它

定义动作响应函数

要在插件中执行动作，就要先在插件文件(必须放到wp-content/plugins下)中定义一个响应动作的 PHP 函数。比如下面的例子，实现的功能是在新文章发布时，通过电子邮件通知好友。

function email_friends($post_ID)  {
    $friends = 'bob@example.org,susie@example.org';
    mail($friends, "sally's blog updated", 
      'I just put something on my blog: http://blog.example.com');
    return $post_ID;
}

在大多数的动作会向响应它的函数传递一个参数(根据实际情况可能是文章ID也可能是评论ID)。而有些动作则会传递多个，具体情况请参见文档以及 WordPress 的源代码。当然除了传进来的参数以外，响应的函数还可以调用 WordPress 的全局变量和函数，也可以调用插件自定义的变量和函数。

如果插件中有直接输出结果的指令的话(例如 print 或 echo)，那么输出的内容将根据该动作所执行的时间，出现在页面对应的地方。

避免函数命名冲突

很可能其他人开发的插件的函数名和你的插件的函数名一样！

这是一个问题，因为PHP不允许多个具有相同名称的函数。如果两个插件提供了具有相同名称的函数，或插件的函数名称和WordPress内置函数的名称一样，博客可能会停止运作。避免这个问题的方法有两种。

第一个解决方案是你的插件使用独特的函数前缀，比如 WordPress大学 可用 wpdaxue_output(){…} 。

第二个——可能更容易——的解决方案是，附上您的插件功能类和静态调用类的方法。这听起来比它更复杂。

考虑这个类，它扩展了上面提供的例子：

class emailer {
  function send($post_ID)  {
    $friends = 'bob@example.org,susie@example.org';
    mail($friends,"sally's blog updated",'I just put something on my blog: http://blog.example.com');
    return $post_ID;
  }
}

add_action('publish_post', array('emailer', 'send'));

这个类，称作 emailer  提供了一个方法 send  实现了这个插件的功能。

add_action() 函数在类的外部添加了动作到 WordPress 来告诉它当文章发布的时候，调用 send 。数组（array ）的第二个参数告诉插件系统来调用名为“send” 的 ’emailer’ 类的静态方法。

函数 send 通过类声明来区别全局于命名空间。它是不可能直接调用 send() 函数的，所以即使其他函数命名为send ，也不会和这个冲突。如果你一定要调用 send() ，就必须使用范围解析运算符，像这样 emailer::send()

上面的例子是静态方法。如果你有一个类的实例，那么将无法正常工作。要调用一个实例的方法，你需要传递这个实例作为一个变量。考虑到这点，可以修改上面的例子中：

class emailer {
  function send($post_ID)  {
    $friends = 'bob@example.org,susie@example.org';
    mail($friends,"sally's blog updated",'I just put something on my blog: http://blog.example.com');
    return $post_ID;
  }
}
$myEmailClass = new emailer();
add_action('publish_post', array($myEmailClass, 'send'));

类是一个复杂的课题。阅读更多 PHP documentation on classes.

挂载进 WordPress

定义完动作响应函数之后，下一步就得把这个函数挂载(或者说注册)到 WordPress 里面去。做法是在插件中调用 add_action() 函数，如下：

add_action ( '动作名', '响应函数名', [优先级], [参数数目] );

参数说明：

动作名

WordPress 所提供的动作名，用于标识在哪个动作发生时，执行响应函数

响应函数名

当动作 hook_name 发生时需要执行的响应函数的名字。可以是 PHP 标准的函数，或者是 WordPress 内的函数，或者是插件内自定义的函数，例如上述例子中的 ’email_friends’

优先级

这是一个可选的参数，默认值为10。由于可以把多个函数注册到同一个动作，所以这个参于是用于指定注册到这个动作中的这个函数执行的优先级，数字越小优先级越高，执行得也越早，反之亦然。如果若干个函数以相同的优先级注册到同一个动作，那么执行顺序则是由它们注册的先后顺序所决定。

参数数目

这是一个可选的参数，确认值是1。由于某些动作可能会把多个参数传给响应函数，所以这个有时候需要指定响应函数能接受多少个参数。这个参数是在 1.5.1 版加进去的。

返回的值

第一个参数传递给过滤（filter）函数的值

要是回来讨论之前的例子，我们可以这样把函数挂载到系统中：

add_action ( 'publish_post', 'email_friends' );

在动作挂载进去之后，也可以删除动作。

安装和启用

安装文件并且激活插件之后，那么你的动作挂钩就可以使用了。你编写的PHP函数以及 add_action 调用必须保存在同一个PHP文件当中，并且这个PHP文件必须安装（保存）到wp-content/plugins目录下。一旦安装成功，你将需要打开WordPress的管理员页面并且激活你的插件。更多信息，请参见Managing Plugins。

目前提供的动作类挂钩

参看 Plugin API/Action Reference 以查找WordPress目前提供的动作类挂钩列表，以及过去版本WordPress的动作类挂钩的链接。

过滤器

过滤器是一类函数，WordPress执行传递和处理数据的过程中，在针对这些数据做出某些动作之前的特定点运行(例如将数据写入数据库或将其传递到浏览器页面)。过滤器处于数据库与浏览器中间(当WordPress正在产生页面的时候)，处于浏览器与数据库之间(当WordPress添加新的文章评论到数据库的时候)；WordPress中的多数输入与输出都经过至少一个过滤器。WordPress默认状态做了一些过滤，你的插件可以添加它自己的过滤器。

添加你自己过滤器到WordPress中的基本步骤如下(在下面描述了更多细节)：

1. 创建过滤数据的PHP函数。
2. 在WordPress中通过钩子接入过滤器，通过引用add_filter()
3. 把你自己的PHP函数放进一个插件文件，并激活它。

创建过滤器函数

一个过滤器函数在输入未调整数据时发挥作用，并返回调整后的数据(或在某些情况，是一个空值以指示这个数据应该被删除或忽略)。如果数据没有被你的过滤器处理，那么初始数据必须必被返回，这样后续的插件可以在必要的时候继续来修正它的值。

因此，创建你插件中过滤器的第一步就是创建一个PHP函数来执行过滤，并把它存入你的插件文件中(你的插件文件必须要置于wp-content/plugins目录下)。例如，如果你需要确认你的文章和评论中没有包含脏话，你可以定义一个包含禁用词语列表的全局变量，然后创建下面的PHP函数：

function filter_profanity( $content ) {
	$profanities = array('badword','alsobad','...');
	$content = str_ireplace( $profanities, '{censored}', $content );
	return $content;
}

为什么这个例子没有一个循环？因为 $profanities 是一个数组，使用 str_ireplace 函数传递数组。使用 str_ireplace 函数而不用 str_replace ，是因为 str_ireplace 不区分大小写。

注意: 始终留意你想到的函数名是不是可能在其它插件或WordPress核心函数中已经被使用了。参看Plugin Development Suggestions了解更多信息。

挂载你的过滤器

在你的函数定义完成后，下一步就是钩入或者说在WordPress中注册它。为了达到这一点，在你插件的全局执行空间引用add_filter():

add_filter ( 'hook_name', 'your_filter', [priority], [accepted_args] );

参数说明：

hook_name

WordPress提供的过滤器钩子，这钩子定义了你的过滤器何时会被执行。

your_filter

你希望用来执行过滤功能的函数名称。这可以是一个标准的PHP函数，一个标准的WordPress核心函数，或者是一个你在一个插件文件中定义过的函数。

priority

可选，整型参数，用来确定与特定过滤器相关联的函数在执行过程中的顺序(默认为10)。具有相同优先权的函数在执行时的顺序依据它们在过滤器中的添加顺序。

accepted_args

可选，整型参数，定义了你的函数可以接受多少参数(默认为1)。有一定作用价值，因为一些钩子会传递多于一个的参数给你的函数。

在上面的例子中，我们应当把下面代码放入插件文件的主要执行段，来告诉WordPress来过滤有脏话的评论:

add_filter('comment_text','filter_profanity');

你也可以使用remove_filter()函数把过滤器钩子上的过滤器移除。参看Removing Actions and Filters

安装并激活

要使你的钩子生效，你需要做的最后一步是安装并激活插件。你写的PHP函数和 add_filter() 必须在一个PHP文件中，该PHP文件必须安装在wp-content/plugins目录。安装完毕之后，你需要访问WordPress后台，然后激活你的插件。详情请访问Managing Plugins。

目前为过滤器提供的钩子

参看 Plugin API/Filter Reference 查找目前为WordPress过滤器提供的钩子, 以及过去版本WordPress钩子的链接。

示例

在wp-hackers邮件列表中Ozh所描述的, 这个插件用于修改(或者覆盖)默认的 bloginfo() 函数。 这将需要修改一个核心函数的行为。

add_filter( 'bloginfo', 'mybloginfo', 1, 2 );
add_filter( 'bloginfo_url', 'mybloginfo', 1, 2 );

function mybloginfo( $result='', $show='' ) {
	switch ( $show ) {
		case 'wpurl':
			$result = SITE_URL;
			break;
		case 'template_directory':
			$result = TEMPL_DIR;
			break;
		default: 
	}
	return $result;
}

移除钩子与过滤器

在某些情况，你会发现你需要关闭你插件或其它插件创建入WordPress的一个动作或过滤器。你可以通过引用remove_filter(‘filter_hook’,’filter_function’)或remove_action(‘action_hook’,’action_function’)来完成。

例如，remove_action(‘publish_post’,’generic_ping’);会在你的新博文发布的任何时候阻止你的博客发送pings值。

注意如果一个钩子如果被注册了超过优先权默认值10的函数，那么你也必须在使用remove_action()指定优先权。也要注意，通常，你不应该移除任何东西除非你知道它是干什么的以及它为什么要这么做–检查WordPress或是其它插件代码来确认。

可重写的函数

除了上面描述的钩子(动作和过滤器)，还有另外一个插件办法来处理WordPress的行为，那就是重写WordPress的函数。事实上，有一小部分函数是WordPress准备好用来重新定义的。仅当在所有插件被加载，它们还没有被重新定义的时候WordPress加载这些函数。查看wp-settings.php了解更多。

启用/禁用/卸载

如果你的插件在启用或禁用时有任务要进行，你可以使用 register_activation_hook 和 register_deactivation_hook。大多数的插件不需要使用这些，它们只是修改当前的行为。但是，如果你的插件（例如）需要修改默认的启用选项，它可以使用这些函数。

创建表插件 这个例子使用的 register_activation_hook 函数，使数据库与当前版本的插件兼容。

register_uninstall_hook 可以让你的插件在删除以后进行清理操作。用户禁用插件的原因很多，所以不要通过 register_deactivation_hook 挂钩删除用户的设置，而应该使用 register_uninstall_hook 挂钩。

• 原文：http://codex.wordpress.org/Plugin_API
• 编译：倡萌@WordPress大学 （参考官方中文文档）