Languages: English • Español • API 日本語 中文(简体) • (Add your language)
本文介绍的是一些为 WordPress 插件开发者提供的 API (编程语言接口)，以及如何调用这些接口。
阅读本文之前，请先参考开发一个插件，以便了解一些关于插件的概况和详情。文本着重于“执行挂勾”类的接口，这类接口也被称为“过滤器”(Filters)和“动作”(Actions)，WordPress 正是使用这种接口把插件挂接到系统中的。当然，也可在主题文件里面调用这类接口，请参考：主题函数文件
注意： 本文的内容适用于 WordPress 1.2 或更高版本。对于 1.2 之前的版本，只有通过修改 WordPress 的源代码来对系统进行扩展。
WordPress 中有一种叫执行挂勾的机制，允许插件把一些功能“挂载”到 WordPress 当中。也就是说，在系统运行至某一个环节时，去调用插件内的一些函数。执行挂勾分为两种：
某些时候动作或过滤器可以达到相同的效果。比如要修改文章的内容，可以把插件挂载到动作 publish_post 上，在文章的内容保存到数据库前就修改它。也可以把插件挂载到过滤器 the_content 上，在文章的内容发送到浏览器前修改它。
如果要查询 WordPress 中所有的标准的动作和插件，请参考： Adam Brown 的 WordPress 执行挂勾数据库。
|
|
| 激活与屏蔽挂勾的函数 | |
|---|---|
动作 (Actions) 是由 WordPress 内部的某些事件所触发的，比如说发表一篇文章、更换主题或者访问后台的某个管理界面，这些都是一件事件的例子。而插件则可以指定某些 PHP 函数来响应这些事件所触发的动作。例如：
使用动作来挂载插件的基本步骤如下：
要在插件中执行动作，就要先在插件文件(必须放到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)，那么输出的内容将根据该动作所执行的时间，出现在页面对应的地方。
注意：在插件内定义函数时，有可能会跟其它的插件或者 WordPress 里面的函数重名，所以在命名前请先参考：避免命名冲突。
定义完动作响应函数之后，下一步就得把这个函数挂载(或者说注册)到 WordPress 里面去。做法是在插件中调用 add_action() 函数，如下：
add_action ( '动作名', '响应函数名', [优先级], [参数数目] );
参数说明：
要是回来讨论之前的例子，我们可以这样把函数挂载到系统中：
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中的基本步骤如下(在下面描述了更多细节)：
一个过滤器函数在输入未调整数据时发挥作用，并返回调整后的数据(或在某些情况，是一个空值以指示这个数据应该被删除或忽略)。如果数据没有被你的过滤器处理，那么初始数据必须必被返回，这样后续的插件可以在必要的时候继续来修正它的值。
因此，创建你插件中过滤器的第一步就是创建一个PHP函数来执行过滤，并把它存入你的插件文件中(你的插件文件必须要置于wp-content/plugins目录下)。例如，如果你需要确认你的文章和评论中没有包含脏话，你可以定义一个包含禁用词语列表的全局变量，然后创建下面的PHP函数：
function filter_profanity($content) {
global $profanities;
foreach($profanities as $profanity) {
$content=str_ireplace($profanity,'{censored}',$content);
}
return $content;
}
注意: 始终留意你想到的函数名是不是可能在其它插件或WordPress核心函数中已经被使用了。参看Plugin Development Suggestions了解更多信息。
在你的函数定义完成后，下一步就是钩入或者说在WordPress中注册它。为了达到这一点，在你插件的全局执行空间引用add_filter:
add_filter ( 'hook_name', 'your_filter', [priority], [accepted_args] );
where:
In the example above, we would put the following in the main executing section of the plugin file, to tell WordPress to filter comments for profanity: 在上面的例子中，我们应当把下面代码放入插件文件的主要执行段，来告诉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了解更多。
这些函数被定义于wp-includes/pluggable.php。这里有一个2.7.1版本的表；它们中少数部分的文档可以在Function Reference找到。