WordPress 中插件开发的相关 API 详解

Question

本文档介绍了在 WordPress 中对插件开发者有用的 API 的使用方法，本文主要就介绍 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 动作是 WordPress 程序核心在程序执行的特殊点（特定事件发生）加载的。使用 Action API，你的插件可以在这些特殊点执行一个或者多个在插件中编写的 PHP 函数。
2. 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: https://www.wenjiangs.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 的最可靠方法是在 WordPres s核心文件中搜索 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

https://www.wenjiangs.com/doc/add-action

https://www.wenjiangs.com/doc/add-filter