WordPress插件开发API文档中文版

一、简介

本文假设您已阅读编写插件，提供如何开发插件的概述（和许多细节）。同样专门针对 API“挂钩”，也称为“过滤器”和“操作”，WordPress 使用它们在运行时设置您的插件。

二、钩子：动作和过滤器

钩子由 WordPress 提供，允许您的插件“钩入”WordPress 的其余部分；也就是说，在特定时间调用插件中的函数，从而使插件运行。有两种钩子：

• Actions
• Filters

有时，您可以使用操作或过滤器来实现相同的目标。例如，如果您希望您的插件更改帖子的文本，您可以添加一个 action 函数到publish_post（这样帖子在保存到数据库时被修改），或者一个过滤器函数到the_content（所以帖子是修改为在浏览器屏幕中显示）。

三、函数参考

1、过滤功能 Function Reference

• Filter Functions
• has_filter()
• add_filter()
• apply_filters()
• apply_filters_ref_array()
• current_filter()
• remove_filter()
• remove_all_filters()
• doing_filter()

2、动作功能 Actions Functions

• has_action()
• add_action()
• do_action()
• do_action_ref_array()
• did_action()
• remove_action()
• remove_all_actions()
• doing_action()

3、激活/停用/卸载功能 Activation/Deactivation/Uninstall Functions

• register_activation_hook()
• register_uninstall_hook()
• register_deactivation_hook()

四、Action操作

操作由 WordPress 中发生的特定事件触发，例如发布帖子、更改主题或显示管理屏幕。Action 是在您的插件（或主题）中定义的自定义 PHP 函数，并挂钩（即设置为响应）其中的一些事件。

操作通常执行以下一项或多项操作：

• 修改数据库数据。
• 发送电子邮件。
• 修改生成的管理屏幕或发送到用户浏览器的前端页面。

1、基本步骤

实现这一目标的基本步骤（在下面更详细地描述）是：

• 在您的插件文件中创建一个应在特定 WordPress 事件发生时执行的 PHP 函数。
• 使用add_action()函数将此函数与事件挂钩。
• 将您的 PHP 函数放在插件文件中，并激活它。

2、创建动作函数

在插件中创建动作的第一步是使用插件的动作功能创建一个 PHP 函数并将其放入插件文件中（你的插件文件必须进入wp-content/plugins目录）。 

例如，如果您希望您的朋友在您创建新帖子时收到一封电子邮件，您可以定义以下函数：

函数 email_friends($post_ID) { $friends = ‘bob@example.org,susie@example.org’; 邮件（$朋友，“莎莉的博客更新”， ‘我只是在我的博客上放了一些东西：http://blog.example.com’); 返回 $post_ID; }

对于大多数操作，您的函数应接受单个参数（通常是帖子或评论 ID，具体取决于操作）。某些操作需要多个参数——查看操作文档（如果可用）或 WordPress 源代码以获取更多信息。除了 one 参数外，您还可以访问WordPress的全局变量，并调用其他 WordPress 函数（或插件文件中的函数）。

函数输出的任何文本（例如打印）将出现在页面源中调用操作的位置。

1）函数名冲突

注意：请记住，其他插件或 WordPress 核心可能已经在使用您想到的函数名称。有关更多信息，请参阅下一节避免函数名称冲突。

2）避免函数名冲突的方法

可能有人创建了一个插件，其函数名称与您插件中的函数名称相同。这是一个问题，因为 PHP 不允许多个具有相同名称的函数。如果两个插件提供同名的功能，或者一个插件提供的功能与 WordPress 功能的名称相同，则博客可能会停止运行。

有两种方法可以避免这个问题。

• 第一个解决方案是为插件中的每个函数添加一组唯一的字符作为前缀。如果您的名字是 John Q. Public，您可以将您的函数声明为

function jqp_output() {...}

具有相同姓名首字母的人用他们的插件做同样事情的可能性是可能的，但很低。

• 第二个 – 可能更简单 – 解决方案是将您的插件函数包含在一个类中并静态调用类方法。这听起来比实际复杂。

考虑这个类，它扩展了上面提供的示例：

类电子邮件{ 静态函数发送（$post_ID）{ $friends = ‘bob@example.org,susie@example.org’; mail($friends,”sally’s blog updated”,’我刚刚在我的博客上放了一些东西：http : //blog.example.com’ ); 返回 $post_ID; } } add_action(‘publish_post’, array(’emailer’, ‘send’));

这个名为emailer 的类有一个方法send来实现插件功能。类外的 add_action() 函数将动作添加到 WordPress，告诉它在发布帖子时调用send方法。第二个参数中使用的数组告诉插件系统调用名为 ‘send’ 的类 ’emailer’ 的静态方法。

3）范围解析运算符

通过类声明，函数send不受全局命名空间的影响。直接调用 send() 是不可能的，因此任何其他名为send 的函数都不会与这个函数发生冲突。如果您确实想调用 send()，则需要使用范围解析运算符，如下所示：

emailer::send()

上面的例子是针对静态方法的。如果您有一个类的实例，那么这将不起作用。要调用实例的方法，您需要将实例作为变量传递。考虑修改上面的示例以考虑到这一点：

class emailer { function send($post_ID) { $friends = 'ToT@example.org,alles@example.org'; mail($friends,"sally's blog updated",'I just put something on my blog: http://blog.example.com'); return $post_ID; } } $myEmailClass = new emailer(); add_action('publish_post', array($myEmailClass, 'send'));

类是一个复杂的主题。在关于类的PHP 文档中阅读更多关于它们的信息。

3、连接到WordPress

定义函数后，下一步是“挂钩”或将其注册到 WordPress。为此，请在插件文件的全局执行空间中调用add_action()：

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

其中：

• 钩子名称：WordPress 提供的动作钩子的名称，它告诉你的函数应该与什么事件相关联。
• your_function_name：您希望在hook_name指定的事件之后执行的函数的名称。这可以是标准的 php 函数、WordPress 核心中的函数或您在插件文件中定义的函数（例如上面定义的“email_friends”）。
• 优先权：一个可选的整数参数，用于指定与特定操作关联的函数的执行顺序（默认值：10）。较低的数字对应于较早的执行，具有相同优先级的函数按添加到操作的顺序执行。
• 接受参数：一个可选的整数参数，定义您的函数可以接受多少个参数（默认为 1），很有用，因为某些钩子可以将多个参数传递给您的函数。此参数是 1.5.1 版中的新参数。

在上面的示例中，我们将以下行放在插件文件中：

add_action ( 'publish_post', 'email_friends' );

同样，您也可以从动作挂钩中删除动作。有关详细信息，请参阅该部分。

4、安装和激活

使您的动作挂钩工作的最后一步是安装文件并激活插件。你写的 PHP 函数和add_action调用必须一起进入一个 PHP 文件，并且 PHP 文件必须安装在wp-content/plugins目录中。安装后，您需要访问 WordPress 的管理部分并激活您的插件；有关更多详细信息，请参阅管理插件。

5、当前的操作钩子

请参阅插件 API/操作参考以获取 WordPress 中的当前操作挂钩列表以及指向 WordPress 以前版本的链接。

五、过滤器

过滤器是 WordPress 在执行中的某些点传递数据的功能，就在对数据采取某些操作之前（例如将其添加到数据库或将其发送到浏览器屏幕）。过滤器位于数据库和浏览器之间（当 WordPress 生成页面时）以及浏览器和数据库之间（当 WordPress 向数据库添加新帖子和评论时）；WordPress 中的大多数输入和输出至少通过一个过滤器。WordPress 默认会进行一些过滤，您的插件可以添加自己的过滤功能。

1、基本步骤

将您自己的过滤器添加到 WordPress 的基本步骤（在下面更详细地描述）是：

• 1. 创建过滤数据的 PHP 函数。
• 2. 通过调用add_filter() 连接到 WordPress 中的过滤器。
• 3. 将您的 PHP 函数放在插件文件中，并激活它。

2、创建过滤器函数

过滤器函数将未修改的数据作为输入并返回修改后的数据（或在某些情况下，返回一个空值以指示应删除或忽略数据）。如果您的过滤器没有修改数据，那么必须返回原始数据，以便后续插件可以在必要时继续修改该值。

因此，在您的插件中创建过滤器的第一步是创建一个 PHP 函数来进行过滤，并将其放入您的插件文件中（您的插件文件必须进入wp-content/plugins目录）。例如，如果您想确保您的帖子和评论不包含任何脏话，您可以定义一个包含禁用词列表的变量，然后创建以下 PHP 函数：

函数 filter_profanity( $content ) { $profanities = array('badword','alsobad','...'); $content = str_ireplace( $profanities, '{censored}', $content ); 返回 $content; }

为什么这在没有循环的情况下工作？因为 $ profanities是一个数组，而str_ireplace 会为您遍历该数组。使用str_ireplace函数代替str_replace是因为str_ireplace不区分大小写。

注意：请记住，其他插件或 WordPress 核心可能已经在使用您想到的函数名称。有关更多信息，请参阅插件开发建议。

3、钩入你的过滤器

定义函数后，下一步是“挂钩”或将其注册到 WordPress。为此，请在插件文件的全局执行空间中调用add_filter()：

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

其中：

• 钩子名称：WordPress 提供的过滤器钩子的名称，它定义了何时应用您的过滤器。
• your_filter：要用于过滤的函数的名称。这可以是标准的 PHP 函数、WordPress 核心中的函数或您在插件文件中定义的函数。
• 优先权：一个可选的整数参数，可用于指定与特定过滤器关联的函数的执行顺序（默认值：10）。较低的数字对应于较早的执行，具有相同优先级的函数按照它们添加到过滤器的顺序执行。
• 接受参数：一个可选的整数参数，定义您的函数可以接受多少个参数（默认为 1），很有用，因为某些钩子可以将多个参数传递给您的函数。
• 返回值：传递给过滤器函数的第一个参数的（可选修改）值。

在上面的示例中，我们将以下内容放在插件文件的主要执行部分，以告诉 WordPress 过滤脏话的评论：

add_filter('comment_text', 'filter_profanity');

您还可以使用remove_filter()函数从过滤器挂钩中删除过滤器。请参阅删除操作和过滤器。

4、安装和激活

使过滤器挂钩工作的最后一步是安装文件并激活插件。你写的 PHP 函数和add_filter()调用必须一起进入一个 PHP 文件，并且 PHP 文件必须安装在wp-content/plugins目录中。安装后，您需要访问 WordPress 的管理部分并激活您的插件；有关更多详细信息，请参阅管理插件。

5、过滤器的当前钩子

请参阅插件 API/过滤器参考以获取 WordPress 中过滤器挂钩的当前列表，以及指向 WordPress 以前版本的链接。

6、示例

这是一个示例，用于插件修改（或覆盖）默认bloginfo()功能。这将需要修改核心功能行为。

add_filter( 'bloginfo', 'mybloginfo', 1, 2 ); add_filter( 'bloginfo_url', 'mybloginfo', 1, 2 ); 函数 mybloginfo( $result='', $show='' ) { 开关 ( $show ) { 案例'wpurl'： $result = SITE_URL; 打破; 案例“模板目录”： $result = TEMPL_DIR; 打破; 默认： } 返回 $result; }

六、删除操作和过滤器

在某些情况下，您可能会发现您希望您的插件禁用 WordPress 内置或由另一个插件添加的操作或过滤器之一。您可以通过调用remove_filter ('filter_hook','filter_function')或remove_action ('action_hook','action_function') 来实现。

例如，remove_action (‘publish_post’,’generic_ping’); 会阻止您的博客在创建新帖子时发送 ping。

请注意，如果使用默认值 10 以外的优先级注册挂钩，则您还必须在调用remove_action() 时指定优先级。另请注意，一般情况下，除非您知道它的作用和原因，否则不应删除任何内容 - 检查 WordPress 或其他插件源代码以确保。

七、可插拔函数

除了上面描述的钩子（动作和过滤器）之外，插件修改 WordPress 行为的另一种方法是覆盖 WordPress 功能。事实上，WordPress 打算为插件重新定义一小组功能。这些被称为可插拔函数，它们在wp-includes/pluggable.php文件。WordPress 仅在加载所有插件后仍未定义这些功能时才加载这些功能。有关更多详细信息，请检查wp-settings.php文件。

八、激活/停用/卸载

如果你的插件有任务只在激活或停用时完成，它可以使用register_activation_hook和register_deactivation_hook。许多插件不需要使用这些，因为插件只修改当前行为。但是，如果您的插件（例如）需要在激活时更改默认选项，它可以使用这些功能。 

使用插件创建表有一个示例，使用register_activation_hook函数使数据库与插件的当前版本兼容。

该register_uninstall_hook给你的插件，当它从WordPress安装删除后自己清理的选项。用户有理由暂时停用插件，因此不要从停用挂钩中执行任何会丢失任何用户设置的操作。这就是卸载钩子的用途。