深入探索 WordPress 插件开发中的核心 API 解析-wordpress插件主题

轻松了解 WordPress 插件开发中的 Hook API

今天我们聊聊在 WordPress 插件开发中非常实用的 API，主要聚焦于 Hook API，比如 Filters 和 Actions。这些工具可以帮助你把插件顺利加载到 WordPress 中。

要注意的是，这里提到的内容适用于 WordPress 1.2 及以上版本。在 1.2 之前，插件被称为 hacks，通常是通过直接修改 WordPress 源代码来实现功能的。

翻译小贴士：为了更好地理解原文中的内容，有些专业术语我们没有翻译，你可以参考以下词汇表：

API：应用程序编程接口。
Hook：钩子，让你能在 WordPress 处理流程中插入自己的功能。
Filter：过滤器。
Action：动作。

Hook：Actions 和 Filters

Hook 是 WordPress 提供的一种机制，可以让你的插件在特定时刻执行你的代码，简单来说，就是在 WordPress 运行时，允许你插入自定义的处理逻辑。WordPress 提供了两种主要的 hook：

Action（动作）：在 WordPress 执行特定事件时加载，比如发布文章或更新主题。通过 Action API，你的插件可以在这些关键时刻运行一个或多个你编写的 PHP 函数。
Filter（过滤器）：用于在数据存入数据库或发送到浏览器之前，对其进行处理。利用 Filter，你的插件可以对文本进行各种处理。

有时候，你可以用 Action 和 Filter 达成相同的目的。比如，如果你有一个插件是用来修改博客文章的内容，你可以在文章存入数据库时使用 Action，也可以在文章显示给用户之前使用 Filter。

Actions（动作）

Action 是在 WordPress 特定事件发生时被触发的，比如发布文章、修改主题或者在后台管理页面加载时。你的插件可以通过执行 PHP 函数来进行操作，这些操作可以包括：

更新数据库中的信息
发送电子邮件通知
修改浏览器中显示的信息（无论是管理员还是普通访客看到的）

实现 Action 的基本步骤如下：

在你的插件中编写一个 PHP 函数，当事件发生时执行它。
使用 add_action 函数将这个操作勾入 WordPress。
将你的 PHP 函数放在插件文件中，并激活插件。

编写 Action 函数

创建 Action 的第一步是在插件中写一个 PHP 函数，并将其放在你的插件文件里（这个文件需要放在 wp-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: https://www.wenjiangs.com');  return $post_ID;}

在大多数 Action 中，你的函数通常会接受一个参数（通常是文章或帖子的 ID，这取决于具体操作）。有些 Action 可能还有多个参数，想获取更多信息可以查看 Action 的文档或 WordPress 的源代码。除了函数参数外，你还可以访问 WordPress 的全局变量，并调用 WordPress 中定义的其他函数（或你自己在插件中定义的函数）。

注意：要确保你使用的函数名没有与其他插件或 WordPress 核心冲突，可以查看 避免函数名称冲突获取更多信息。

将函数 Hook 到 WordPress

完成函数编写后，接下来就是将其勾入 WordPress，你可以通过执行 add_action() 函数来实现，示例如下：

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

这里的代码说明：

hook_name 是 WordPress 提供的 Action Hook 名称，用来决定你的函数与哪个事件结合。
your_function_name 是你希望在特定事件后执行的函数名，这可以是标准的 PHP 函数、WordPress 核心中的函数，或者你在插件中定义的函数（比如我们刚才的 email_friends 函数）。
priority 是可选参数，用来指定多个函数结合同一事件时的执行顺序（默认是 10）。数字越小，执行越早；如果多个函数的优先级相同，则按它们被添加的顺序执行。
accepted_args 是一个可选的整型参数，定义你的函数可以接收多少个参数（默认是 1）。这个参数很有用，因为某些 Hook 可能会传递多个参数。这个参数是在 1.5.1 版本中新增的。

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

add_action('publish_post',  'email_friends');

同样，你也可以在 Action Hook 中移除 Action，具体可以参考移除 Actions获取更多信息。

安装和激活

最后一步是安装并激活插件文件，让你的 Action Hook 开始工作。你需要将编写的 PHP 函数和 add_action 函数放在同一个 PHP 文件中，并且把这个文件放在 wp-content/plugins 目录下。安装完成后，记得去 WordPress 的管理面板激活你的插件，具体可以参考管理插件了解更多。

当前可用的 Action Hook

想查看 WordPress 中当前版本可用的 Action Hook，可以访问插件 API/Action 参考。

Filters（过滤器）

Filters 是 WordPress 在执行过程中针对特定数据传递的函数，通常发生在数据被写入数据库或发送到浏览器之前。Filter 处理的是从数据库到浏览器的数据（比如 WordPress 生成页面时），以及从浏览器到数据库的数据（比如 WordPress 新增日志或评论时），在 WordPress 中，几乎所有的输入输出都至少经过一个 filter。WordPress 默认实现了一些过滤器，你的插件也可以添加自己的过滤器。

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

编写一个用于过滤数据的 PHP 函数。
通过执行 add_filter 函数将 filter 勾入 WordPress。
将你的 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 核心冲突，参考避免函数名称冲突获取更多信息。

Hook（勾入）到 WordPress

完成函数编写后，接下来就是将其勾入 WordPress，你可以通过执行全局空间中的 add_filter() 函数来实现：

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

这里的代码说明：

了解 WordPress 的 Filter Hook

首先，hook_name 是 WordPress 提供的过滤器钩子的名称，它告诉你的函数什么时候发挥作用。
接下来，your_filter 是你用来过滤的函数名称。这个函数可以是 PHP 标准函数，也可以是 WordPress 核心中已有的函数，或者你自己在插件中定义的函数。
还有一个 priority 参数，这个是可选的，告诉 WordPress 在多个处理同一事件的函数中，当前函数的执行顺序（默认值是 10）。数字越小，执行越早；如果有多个函数的优先级相同，它们会按照添加的顺序来执行。
accepted_args 是另一个可选的参数，用来定义你的函数能接收多少个参数（默认为 1）。这个参数特别有用，因为有些钩子会传递多个参数给你的函数。这个参数是在 1.5.1 版本中新增的。

在之前的例子中，你可以把下面的代码放入插件文件的主执行部分，来告诉 WordPress 过滤评论中的脏话：

add_filter('comment_text', 'filter_profanity');

如果你想移除某个过滤器，可以使用 WordPress 的 remove_filter() 函数。你可以查看删除 Actions 和 Filters 来获取更多信息。

安装与激活

让你的 Filter Hook 正常运行的最后一步，就是安装和激活插件。你需要把写好的 PHP 函数和 add_filter 函数放在同一个 PHP 文件中，并把这个文件放到 wp-content/plugins 目录下。文件安装完后，去 WordPress 的管理面板激活你的插件，想了解更多可以看看管理插件的相关内容。

当前可用的 Filter Hook

你可以访问插件 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以外），你需要在 remove_action() 函数中调整 priority 的参数。同时，除非你清楚这样做的目的和后果，否则最好不要随意移除任何内容，建议查看 WordPress 或其他插件的源代码来确保安全。