学习笔记6——插件 API，“过滤器”(Filters)和“动作”(Actions)

WordPress 中有一种叫执行挂勾的机制，允许插件把一些功能“挂载”到 WordPress 当中。也就是说，在系统运行至某一个环节时，去调用插件内的一些函数。执行挂勾分为两种：

1. 动作 (Action)： 动作是 WordPress 运行到某些环节，或者在某些事件发生时，就会被执行的一种挂钩。任何的插件都可以通过动作接口来指示系统在遇到这些环节或者事件的时候，就执行指定的 PHP 函数。
2. 过滤器 (Filter)：过滤器的是 WordPress 用于修改即将要保存或者发送出去的数据的一种挂钩。任何的插件都可以通过过滤器接口来指示系统在遇到某些环节或者事件的时候，就执行指定的 PHP 函数去修改特定的数据。

某些时候动作或过滤器可以达到相同的效果。比如要修改文章的内容，可以把插件挂载到动作 publish_post 上，在文章的内容保存到数据库前就修改它。也可以把插件挂载到过滤器 the_content 上，在文章的内容发送到浏览器前修改它。

使用动作来挂载插件的基本步骤如下：

1. 在插件代码中定义当某个事件发生时，需要执行的 PHP　函数
2. 用add_action() 把这个函数注册到动作执行挂勾上
3. 把插件源码放到 WordPress 指定的地方，然后启用它 

   定义动作响应函数

   要在插件中执行动作，就要先在插件文件(必须放到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

   定义完动作响应函数之后，下一步就得把这个函数挂载(或者说注册)到 WordPress 里面去。做法是在插件中调用 add_action() 函数，如下：

   add_action ( '动作名', '响应函数名', [优先级], [参数数目] );  //wp中比较重要的一个函数
   

   参数说明：

   动作名 

   WordPress 所提供的动作名，用于标识在哪个动作发生时，执行响应函数，所有的动作名可以参考 https://codex.wordpress.org/Plugin_API/Action_Reference 查询钩子的技巧：例如想查询关于文章的钩子可以在浏览器查询_post进行查询。

   响应函数名 

   当动作 hook_name 发生时需要执行的响应函数的名字。可以是 PHP 标准的函数，或者是 WordPress 内的函数，或者是插件内自定义的函数，例如上述例子中的 'email_friends'

   优先级 

   这是一个可选的参数，默认值为10。由于可以把多个函数注册到同一个动作，所以这个参于是用于指定注册到这个动作中的这个函数执行的优先级，数字越小优先级越高，执行得也越早，反之亦然。如果若干个函数以相同的优先级注册到同一个动作，那么执行顺序则是由它们注册的先后顺序所决定。

   参数数目 

   这是一个可选的参数，确认值是1。由于某些动作可能会把多个参数传给响应函数，所以这个有时候需要指定响应函数能接受多少个参数。这个参数是在 1.5.1 版加进去的。

   要是回来讨论之前的例子，我们可以这样把函数挂载到系统中：

   add_action ( 'publish_post', 'email_friends' );
   

   在动作挂载进去之后，也可以删除动作。

   安装和启用

   安装文件并且激活插件之后，那么你的动作挂钩就可以使用了。你编写的PHP函数以及 add_action 调用必须保存在同一个PHP文件当中，并且这个PHP文件必须安装（保存）到wp-content/plugins目录下。一旦安装成功，你将需要打开WordPress的管理员页面并且激活你的插件。更多信息，请参见Managing Plugins。

   过滤器

   过滤器是一类函数，WordPress执行传递和处理数据的过程中，在针对这些数据做出某些动作之前的特定点运行(例如将数据写入数据库或将其传递到浏览器页面)。过滤器处于数据库与浏览器中间(当WordPress正在产生页面的时候)，处于浏览器与数据库之间(当WordPress添加新的文章评论到数据库的时候)；WordPress中的多数输入与输出都经过至少一个过滤器。WordPress默认状态做了一些过滤，你的插件可以添加它自己的过滤器。

   
   添加你自己过滤器到WordPress中的基本步骤如下(在下面描述了更多细节)：

   1. 创建过滤数据的PHP函数。
   2. 在WordPress中通过钩子接入过滤器，通过引用add_filter
   3. 把你自己的PHP函数放进一个插件文件，并激活它。

   创建过滤器函数

   一个过滤器函数在输入未调整数据时发挥作用，并返回调整后的数据(或在某些情况，是一个空值以指示这个数据应该被删除或忽略)。如果数据没有被你的过滤器处理，那么初始数据必须必被返回，这样后续的插件可以在必要的时候继续来修正它的值。

   
   因此，创建你插件中过滤器的第一步就是创建一个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', '过滤函数名', [priority], [accepted_args] );
   

   where:

   hook_name 

   WordPress提供的过滤器钩子，这钩子定义了你的过滤器何时会被执行。

   your_filter 

   你希望用来执行过滤功能的函数名称。这可以是一个标准的PHP函数，一个标准的WordPress核心函数，或者是一个你在一个插件文件中定义过的函数。

   priority 

   可选，整型参数，用来确定与特定过滤器相关联的函数在执行过程中的顺序(默认为10)。具有相同优先权的函数在执行时的顺序依据它们在过滤器中的添加顺序。

   accepted_args 

   可选，整型参数，定义了你的函数可以接受多少参数(默认为1)。有一定作用价值，因为一些钩子会传递多于一个的参数给你的函数。