WordPress:插件开发API(Plugin API)

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函数来响应事件,实现以下几个目的:

  • 修改数据库数据

  • 发送Email信息

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


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

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

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

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


创建一个Action 函数


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

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;
}

对于大多数的Action来说,您的函数要接受一个单一参数(通常是日志或这评论的ID,这要视情况而定)。有些Action接受多于一个的参数, 您可以查看WordPress的Action文档,或者直接查看WordPress源代码来取得第一手资料。除了一个参数外,您还可以访问 WordPress的全局变量,并且调用其他WordPress函数或者您插件中的其他函数(或者其他插件中的函数)。
注意:您要始终留意,是否WordPress本身或者其他的插件已经使用了您想用的那个函数的名字。关于这点,您可以查看避免函数名冲突这篇文章来获取更详细的信息。

Hook到WordPress


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

该函数中:

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

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

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

  • 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中,遵循以下几个步骤:

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

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

  • 将您的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]);

其中:

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

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

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

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


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

add_filter(’comment_text’,'filter_profanity’);

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

安装和激活


最后一个步骤就是使您的filter运作起来。你需要做的就是将您的插件文件放到/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文件中进行的。其他的在下列的文件中加载:

  • wp-admin/admin-ajax.php

  • wp-admin/admin-functions.php

  • wp-admin/custom-header.php

  • wp-admin/edit.php

  • wp-admin/index.php

  • wp-admin/options-permalink.php

  • wp-admin/upload-functions.php

  • wp-admin/upload.php

  • wp-includes/bookmark.php

  • wp-includes/general-template.php

  • wp-includes/kses.php

  • wp-includes/plugin.php

  • wp-includes/rewrite.php

  • wp-includes/template-loader.php

  • wp-includes/theme.php


WordPress 2.5


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

您可以覆盖的函数


除了使用hook(action和filter),另一个插件修改Wordpress行为方式是覆盖WordPress的函数。实际上,有一小组函 数,是WordPess希望被插件覆盖的。在所有的插件都已经启动后,如果他们还没有被覆盖的话,WordPress才启动这些函数。
这些函数在wp-include/pluggable.php文件中定义。这里有一个列表(WP2.1)。

  • set_current_user

  • wp_set_current_user

  • wp_get_current_user

  • get_currentuserinfo

  • get_userdata

  • update_user_cache

  • get_userdatabylogin

  • wp_mail

  • wp_login

  • is_user_logged_in

  • auth_redirect

  • check_admin_referer

  • wp_redirect

  • wp_get_cookie_login

  • wp_setcookie

  • wp_clearcookie

  • wp_notify_postauthor

  • wp_notify_moderator

  • wp_new_user_notification

  • wp_verify_nonce

  • wp_create_nonce

  • wp_salt

  • wp_hash

Need a translation service?

Please enter your personal details and we will contact you shortly

Words translated by CCJK

146,096,379

We are Certified

Our Client Satisfaction

rating for previous quarte

4.00

Over 95% of our clients recommend our language services to others

Copyright © CCJK Technologies Co., Ltd. 2000-2017. All rights reserved.
TOP