WordPress插件API手册

转载的，但找不到最初的地址了

概述

本文档介绍了在WordPress中对插件开发者有用的API（Application Programming Interface，应用编程接口）的使用方法。

本文假设你已经阅读了简要介绍插件开发方法的文章：Writing a Plugin，本文主要就介绍Hook API，比如Filters、Action，这使得WordPress可以加载你的插件。

注意：本文所提到的信息针对WordPress1.2及以上版本，在1.2版之前，这些插件被称为“hacks”，他们主要是通过修改WordPress本身的源码来实现的。

译者注：在本文中，为了便于对原文的准确翻译，一些程序设计的专有词汇没有进行翻译，你可以阅读如下单词表来参考：

• API，应用程序编程接口。
• Hook，钩子，意为在WordPress的处理中加入你自己的处理。
• Filter，过滤器。
• Action，动作。

Hooks，Actions和Filters

Hook是WordPress提供的，允许你的插件“勾入”WordPress的程序，或者说，可以在特定时候执行你插件中的函数，从而使得你的插件执行。这里提供了两种hook：

1. Action：Action（动作）是WordPress程序核心在程序执行的特殊点（特定事件发生）加载的。使用Action API，你的插件可以在这些特殊点执行一个或者多个在插件中编写的PHP函数。
2. Filter：Filter（过滤器）是WordPress加载的，当文本被存入数据库或发送到浏览器之前，Filter可用来对其进行多种类型的处理。使用Filter，你的插件可以使用定义在其中的PHP函数来对文本进行多种处理。

某 些时候，你可以用Action或者Filter实现同样的功能。举例来说，如果你编写了一个插件用来修改博客日志的文本，你可以加入一个Action函数 到publist_post的事件（这样日志就会在存入数据库时被修改），也可以加入一个Fliter函数到the_content（这时日志内会在显示 到浏览器之前被修改）。

Actions（动作）

Action（动作）在WordPress进行某些特殊事件处理时被触发，例如发布日志，修改主题，或者在管理员面板显示页面。你的插件可以通过执行PHP函数来发挥作用，他们可以用来做如下事情：

• 修改数据库中的数据
• 发送Email消息
• 修改在浏览器中显示的信息（包括管理员看到的和访问者看到的）

实施Action的基本步骤是：

1. 在你的插件中编写当事件发生时执行的PHP函数。
2. 通过执行add_action函数将这些操作Hook（勾入）到WordPress中。
3. 将你的PHP函数放入插件文件，并且将其激活。

编写Action函数

在插件中创建Action的第一步是在插件中编写一个实现Action功能的PHP函数并且将其放入你的插件文件（插件文件必须放置在wp- content/plugins目录）中。比如，如果你希望当发表一篇日志后，发送Email通知给你的朋友，那么你可以定义如下函数：

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中，你的函数应该接受一个参数（通常是日志或者帖子的编号，这取决于你要进行的操作）。某些Action可能有多余一个参数 –你可以通过查看Action的文档或者WordPress源代码来获得更多信息。除函数参数外，你还可以访问WordPress的全局变量以及执行 WordPress中定义的其他函数（或者在你的插件文件中定义的函数）。

注意：切记其他插件或者WordPress核心可能已经使用了你希望使用的函数名称，你可以浏览Avoiding Function Name Collisions（避免函数名称冲突–译者注）来获得更多信息。

Hook（勾入）到WordPress

完成你的函数的编写后，下一步就是将其hook（勾入）或者说注册到WordPress中，你可以通过执行全局空间中的add_action()函数来实现，如：

add_action ( 'hook_name', 'your_function_name', [priority], [accepted_args] );

此处

• hook_name参数是WordPress提供的Action Hook（动作钩子）名称，这决定了你的函数应当和哪个事件结合。
• your_function_name参数是你希望在特定事件（即hook_name参数指定的事件）后执行的函数名称。该函数可以是 标准的PHP函数，在WordPress核心中定义的函数或者你自己在插件文件中定义的函数（如刚才我们编写的emai_friends函数）。
• priority参数是一个可选的整型参数，他用来指明在结合特定事件的多个函数中，当前函数被执行的顺序（默认为10）。该参数指定的更小的数字会被更早的执行，priority参数相同的函数会依照他们被加入Action的顺序来执行。
• accepted_args参数是一个可选的整型参数，他定义了你的函数中可以接收多少个参数（默认为1）。该参数是非常有用的，因为某些Hook可以向你的函数中传入多个参数。该参数在1.5.1版本中被新加入。

在前面的例子中，我们可以在插件文件中加入如下代码：

add_action('publish_post', 'email_friends');

同样的，你也可以在Action Hook中移除Action，你可以参考Remove Actions来获得更多详情。

安装和激活

让你的Action Hook开始工作的最后一步是安装插件文件和激活插件。你必须将你编写的PHP函数和add_action函数存入同一个PHP文件，该PHP文件必须被 安装在wp-content/plugins目录，当该文件安装完毕，你需要浏览WordPress的管理面板，并且激活你的插件，你可以参考Managing Plugins文章来获得更多信息。

当前可用的Action Hook

请浏览Plugin API/Action Reference（插件API/Action参考–译者注）来获得一份当前版本的WordPress中可用的Action Hook。

Filters（过滤器）

Filters（过滤器）是WordPress在执行中的特定点传递数据的函数，他发生在对数据进行操作（如将其加入数据库或发送到浏览器）之前。 Filter建立在数据库到浏览器之间的处理（当WordPress生成页面时），同时也建立在浏览器到数据库之间的处理（当WordPress新增日志 或者评论到数据库时）；多数WordPress中的输入输出都通过了至少一个filter。WordPress默认已经实现了一些过滤操作，你的插件也可 以加入你自己的过滤操作。

将你的filter加入WordPress中的基本步骤如下：

1. 编写用于过滤数据的PHP函数。
2. 通过执行add_filter函数将filter Hook（勾入）到WordPress。
3. 将你的PHP函数放入插件文件，并且将其激活。

编写Filter（过滤器）函数

Filter（过滤器）函数获得未经修改的数据，并返回修改后的数据（或者在某些情况下，返回null值来标识数据应当被删除或忽略）。如果你的filter不修改数据，那么应当返回原始数据，这样，如果必要，其余的插件可以继续修改数据。

因此，在你的插件中创建filter的第一步是编写一个PHP函数来进行过滤处理，并且将其放在你的插件文件（插件文件必须放置在wp- content/plugins目录）当中。例如，如果你希望确保你的帖子和评论中不包含脏话，你可以定义一个存放禁止词汇的全局变量，然后编写如下的 PHP函数：

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


注意：切记其他插件或者WordPress核心可能已经使用了你希望使用的函数名称，你可以浏览Avoiding Function Name Collisions（避免函数名称冲突–译者注）来获得更多信息。

Hook（勾入）到WordPress

完成你的函数的编写后，下一步就是将其hook（勾入）或者说注册到WordPress中，你可以通过执行全局空间中的add_filter()函数来实现，如：

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

此处：

• hook_name参数是WordPress提供的Filter Hook（过滤器钩子）名称，这决定了你的函数在何时发挥作用。
• your_filter参数是你希望用来过滤的函数的名称。该函数可以是标准的PHP函数，在WordPress核心中定义的函数或者你自己在插件文件中定义的函数。
• priority参数是一个可选的整型参数，他用来指明在结合特定事件的多个函数中，当前函数被执行的顺序（默认为10）。该参数指定的更小的数字会被更早的执行，priority参数相同的函数会依照他们被加入Action的顺序来执行。
• accepted_args参数是一个可选的整型参数，他定义了你的函数中可以接收多少个参数（默认为1）。该参数是非常有用的，因为某些Hook可以向你的函数中传入多个参数。该参数在1.5.1版本中被新加入。

在前面的例子中，我们可以将下面的代码放入你的插件文件中的主要执行部分，来通知WordPress对评论中的脏话进行过滤处理：

add_filter(‘comment_text’,’filter_profanity’);

你也可以使用WordPress函数remove_filter()来移除filter hook中的filter。你可以参考Removing Actions and Filters。

安装和激活

让你的Filter Hook开始工作的最后一步是安装插件文件和激活插件。你必须将你编写的PHP函数和add_filter函数存入同一个PHP文件，该PHP文件必须被 安装在wp-content/plugins目录，当该文件安装完毕，你需要浏览WordPress的管理面板，并且激活你的插件，你可以参考Managing Plugins文章来获得更多信息。

当前可用的Filter Hook

请浏览Plugin API/Filter Reference （插件API/Filter参考–译者注）来获得一份当前版本的WordPress中可用的Filter Hook。

删除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在注册时使用了除默认值10意外的priority参数，则你必须修改在remove_action()函数中的 priority参数。同时也请注意，通常来讲除非你知道这样做的原因和后果，你不应当移除任何东西–请检查WordPress或者其他插件的源代码来 保证这一点。

默认应用的Filter和Action

找出WordPress默认启用的filter和Action的最可靠方法是在WordPress核心文件中搜索 add_filter和add_action。

WordPress 2.1

在WordPress 2.1中，大多数默认filter和action是通过文件wp-includes/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 1.5

大多数默认的filter和action在WordPress 1.5的文件wp-includes/default-filters.php中被加入。

你可以覆盖的函数

除了前面描述的hook（包括action和filter）之外，另一个修改WordPress行为的插件编写方法是覆盖WordPress函数。 事实上，WordPress设计了一些让插件重新定义的函数。WordPress通过仅当所有插件都加载之后才加载这些函数的方式来使得这个方式变得容 易。

这些函数均定义在文件wp-includes/pluggable.php中，如下是其清单（在2.1版本中）；这些函数中的部分文档可以在Function Reference（函数参考-译者注）中找到。

• set_current_user
• wp_set_current_user
• wp_get_current_user