Plugin API

介绍

本文当主要介绍WordPress插件开发者可以使用的API Hook,以及如何使用它们。

本文假设您已经阅读了《Writing a Plugin》(这篇文章概览了如何写一个插件)。本文主要介绍API Hook,也称作Filter和Action,WordPress使用这些函数来使您的插件起作用。

注意:本文的内容适用于WordPress1.2+。

Hook,Action和Filter

Hook是WordPress提供的一种机制,帮助您将您的插件加入到WordPress中;也即,在您的插件中,通过调用一些系统函数,使得您的插件可以运作起来。一共有两种Hook:

1) Action:Action是WordPress内核在运行到某个特定的点的,或者某个特定的事件发生的时候执行的。您可以通过使用Action API让您的插件中的一个或者多个函数在这些特定的点执行。

2) Filter:Filter是WordPress在将一段文本加入到数据库,或者发送给浏览器之前处理不同种类的文本用的。您的插件可以通过使用Filter API,让一个或者多个函数在这些时刻运行,以处理特定类型的文本。

有的时候,您可以使用Action和Filter达到相同的目的。比如说,您希望你的插件可以更改一段日志的文本,您可能会往publish_post中添加一个Action函数(这段文字在被加入到数据库之前被修改了),或者往 the_content中添加一个Filter函数(这段文字在被发送给浏览器显示之前,被更改了)。

Action

Action由WordPress中发生的一些特定的事件所触发,比如发布一篇日志,更改主题,或者在管理面板显示一个页面。您的插件可以通过执行一个PHP函数来响应事件,实现以下几个目的:

1) 修改数据库数据

2) 发送Email信息

3) 修改将要在浏览器上呈现的内容(管理员看到的或者访客看到的)

要达到上述的目的,需要遵循的步骤为(下文有详细的描述):

1) 在您的插件文件中,创建一个在某个事件发生时,需要运行的PHP函数。

2) 通过调用add_action函数,将您的函数插入到WordPress中。

3) 将您的插件文件放到插件目录下,然后激活它。

创建一个Action 函数

在您的插件中创建一个Action的第一个步骤是创建一个能响应Action的函数,并且将它写入到您的插件文件里(您的插件文件最后会被放到content/plugins目录)。举个例子,如果您想要您的朋友在您发表了新文章的时候收到一封邮件,您可以创建下述函数:


function email_friends($post_ID) {
$friends = ‘[email protected],[email protected]’;
mail($friends, "sally’s blog updated",
‘I just put something on my blog: https://blog.example.com’);
return $post_ID;
}

对于大多数的Action来说,您的函数要接受一个单一参数(通常是日志或这评论的ID,这要视情况而定)。有些Action接受多于一个的参数, 您可以查看WordPress的Action文档,或者直接查看WordPress源代码来取得第一手资料。除了一个参数外,您还可以访问 WordPress的全局变量,并且调用其他WordPress函数或者您插件中的其他函数(或者其他插件中的函数)。

注意:您要始终留意,是否WordPress本身或者其他的插件已经使用了您想用的那个函数的名字。关于这点,您可以查看避免函数名冲突这篇文章来获取更详细的信息。

Hook到WordPress

当您定义好您的函数后,下一步就是将您的函数Hook或者注册到WordPress中。在您的插件文件中的全局空间中调用函数 add_action()就可以了:

add_action(’hook_name’, ‘your_filter’, [priority], [accepted_args]);

该函数中:

1) hook_name是WordPress提供的供hook用的函数名,也即您的函数将关联到的事件的名称。

2) your_function_name 是您希望在hook_name指定的事件发生时执行的函数的名称。这可以是一个在WordPress中定义好的标准的函数,也可以是一个您自己定义的函数(比如上面提到的email_friends

3) priority是一个可选的整型参数,可以指定可以指定关联到某个特定的函数的执行顺序。默认值是10。数字较小的执行较早,如果优先级相同,则按照他们hook进来的顺序先后来执行。

4) accepted_args是一个可选的整型参数,它定义了您的函数可以接受多少个参数,默认是1。这个参数很有用,因为有些事件发生的时候,可能会向您的函数传递多于一个的参数。这个参数是从WordPress 1.5.1后的版本才开始有的。

继续前文的例子,我们可以将下面一行代码加入到插件的文件中:

add_filter(’comment_text’,'filter_profanity’);

相似的,您也可以将一个函数从Action中移除。你可以参考移除Action来获得详细的信息。

安装和激活

让您的插件奏效的最后一个步骤就是安装和激活和插件了。您写好的函数和对add_action的调用,必须放到同一个文件中,插件文件必须被装到wp-content/plugins目录中。一旦插件安装好,您需要访问管理面板来激活您的插件。

目前已有的Action Hook

参见Plugin API/Action Reference来查看WordPress中的当前的Action列表。

Filter

Filter是在WordPress执行过程中,传递数据时,在对数据采取某种行动(将数据写入到数据库或者发送给访客的浏览器)之前执行的。(当 WordPress生成页面时)Filter就位于数据库和浏览器之间,(当WordPress向数据库添加日志和评论时)Filter就位于浏览器和数 据库之间。WordPress中的绝大多数的输入和输出过程都要通过至少一个Filter。WordPress自己有一些默认的Filter,您可以在插 件中使用自己的Filter。

将您自己的Filter添加到WordPress中,遵循以下几个步骤:

1) 创建一个PHP函数来过滤数据。

2) 通过调用add_filter将这个Filter添加到WordPress中。

3) 将您的PHP函数写入到一个插件文件中,激活它。

创建一个Filter函数

一个Filter函数把未经修改的数据作为输入,返回修改过的数据(或者有的时候返回的空值,表明这些数据应该被删除)。如果您的Filter没有修改数据,那么原始的数据必须被返回回去,以便于后续的插件可以继续它们的修改工作。

所以,在您的插件中创建一个Filter的第一步,就是创建一个PHP函数来执行过滤动作,并且,将这个函数写入到您的插件文件中去。再举个例子, 如果您需要确定您的日志或者评论中没有出现违禁词汇,您可以定义一个全局变量,里面包含了全部的违禁词汇的列表,然后创建下面的PHP函数:


function filter_profanity($content) {
global $profanities;
foreach($profanities as $profanity) {
$content=str_ireplace($profanity,’{censored}’,$content);
}
return $content;
}

注意:同样要小心您的函数的命名,不要和其他的WordPress函数和其他插件的函数冲突。

将您的Filter Hook到WordPress

在您的函数定义完毕后,下一步就是将您的函数”hook”或者说注册到WordPress中。在您的插件文件中,调用add_filter函数:


add_filter(’hook_name’, ‘your_filter’, [priority], [accepted_args]);

其中:

1) hook_name 是WordPress提供的供hook的函数的名称,定义了您可以加入您自己的Filter的插入点。

2) your_filter是您的filter函数的名称。这个函数可以是一个WordPress标准PHP函数,也即在WordPress内核中定义的函数,也可以使一个您自己定义的函数。

3) priority是一个可选的整型参数,标明了注册到某个特定的filter中的函数的执行顺序。默认是10。较小的数字执行时较靠前。如果priority值相同,那么按照注册的先后顺序来执行。

4) accepted_args是一个可选参数,用来标明您的函数能够接受的参数的个数,默认是1,某些hook可以像您的函数传递超过一个的参数。

继续上面的例子,您可以使用下面的代码,让WordPress过滤您评论中的违禁词汇:


add_filter(’comment_text’,'filter_profanity’);

您也可以使用remove_filter()函数来将一个Filter移除。

安装和激活

最后一个步骤就是使您的filter运作起来。你需要做的就是将您的插件文件放到wordpress/plugins目录,然后到后台管理界面激活。

目前WordPress中可以注册的Filter

参见Plugin API/Filter Reference。

例子

下面是一个例子,是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;
}

移除Action和Filter

在某些情况下,您可能会发现,您的插件需要禁用WordPress中的内建Action或者Filter之一,或者某个其它插件添加的函数。您可以通过调用remove_filter(’filter_hook’,'filter_function’)或者 remove_action(’action_hook’,'action_function’)来达到目的。

比如,remove_action(’publish_post’,'generic_ping’);可以在您发表日志的时候,阻止您的博客向外发送ping。

注意,如果一个hook不是使用默认的优先级(priority)注册到系统中,那么您必须在remove_action()中指定那个hook使用的优先级。一般来说还要注意,除非您很清楚那个函数在干什么并且为什么要那么做,请不要移除任何函数。

缺省加载的Filter和Action

最可靠的获知WordPress缺省加载了哪些Filter和Action的方法就是在其源代码中搜索add_filteradd_action函数的调用。

WordPress 2.1

在WordPress2.1中,绝大多数的Filter和Action的加载是在wp-include/default-filters.php文件中进行的。其他的在下列的文件中加载:

1) wp-admin/admin-ajax.php

2) wp-admin/admin-functions.php

3) wp-admin/custom-header.php

4) wp-admin/edit.php

5) wp-admin/index.php

6) wp-admin/options-permalink.php

7) wp-admin/upload-functions.php

8) wp-admin/upload.php

9) wp-includes/bookmark.php

10) wp-includes/general-template.php

11) wp-includes/kses.php

12) wp-includes/plugin.php

13) wp-includes/rewrite.php

14) wp-includes/template-loader.php

  1. wp-includes/theme.php

WordPress 2.5

(以后我会完善这个部分)

您可以覆盖的函数

除了使用hook(action和filter),另一个插件修改Wordpress行为方式是覆盖WordPress的函数。实际上,有一小组函 数,是WordPess希望被插件覆盖的。在所有的插件都已经启动后,如果他们还没有被覆盖的话,WordPress才启动这些函数。

这些函数在wp-include/pluggable.php文件中定义。这里有一个列表(WP2.1)。1) set_current_user

2) wp_set_current_user

3) wp_get_current_user

4) get_currentuserinfo

5) get_userdata

6) update_user_cache

7) get_userdatabylogin

8) wp_mail

9) wp_login

10) is_user_logged_in

11) auth_redirect

12) check_admin_referer

13) wp_redirect

14) wp_get_cookie_login

15) wp_setcookie

16) wp_clearcookie

17) wp_notify_postauthor

18) wp_notify_moderator

19) wp_new_user_notification

20) wp_verify_nonce

21) wp_create_nonce

22) wp_salt

23) wp_hash