WordPress 插件开发教程 – Part-3 – 钩子( hooks )

钩子是 WordPress 的精髓。他们允许插件开发人员钩进 WordPress 工作流程内部来改变它的工作，而不用直接修改核心代码。这就使得用户可以方便的升级到 WordPress 的新版本而不需要修改一行代码。

如果一个开发人员修改了核心代码，这些改动在 WordPress 下一次升级的时候就会消失。升级会覆盖这些改动。使用钩子让你能够在核心以外的目录中单独开发插件，这就在升级时保证了插件代码的安全。

没有钩子，插件就没办法改变 WordPress 的功能了。本节介绍的钩子系统会贯穿整个教程，同时也会在几乎每一个插件的开发中用到。在你学会了钩子的用法后，你就会明白为什么 WordPress 这个平台这么强大，并有上千个插件供几百万用户使用了。

WordPress 主要有两种类型的钩子：动作钩子和过滤器钩子(action hooks and filter hooks )。第一个使得你可以在一个特定时刻上执行一个函数，第二个使得你可以操作通过钩子的输出。

钩子不是仅仅针对插件的。WordPress 内部也使用钩子。如果你浏览核心代码，你就能见到很多 WordPress 自己钩自己的例子了。

动作钩子 ( actions )

动作钩子让你可以在 WordPress 加载过程中或者当某个事件发生的特定时刻触发一个函数。例如：你可能希望当 WordPress 第一次加载一个页面或者保存一篇文章时执行一个函数。

你需要理解 do_action() 函数。当钩进 WordPress 中时，你的插件不会直接调用这个函数；但是你的插件几乎都会间接的使用它。

• $tag — 动作钩子的名称
• $arg — 传递给已注册的动作的值。它看起来像一个单独的参数，但通常都不是这样的。动作钩子可以传递任何个数的参数，或者根本不传参数。对特殊的钩子，你需要查看 WordPress 的源码，因为参数个数在每个钩子的基础改变。

  下面是一个具有多参数的动作钩子的例子：

  下面看看一个叫做 wp_head 的钩子是怎么出现在 WordPress 中的。这个钩子出现在前台的 里面。 WordPress 和插件经常用这个钩子来添加 meta 信息，样式表，和 js 脚本。

  当这段代码在 WordPress 中执行时，它会寻找任何为 wp_head 动作钩子注册的动作。然后按照特殊顺序执行它们。如你所见，它名叫 wp_head 但是没有传递额外的参数。动作钩子通常都这样。下面是有两个额外参数的动作钩子的例子：

  这个 save_post 的钩子传递两个参数，一个 $post_ID，一个 $post。

  什么是动作？

  从技术上讲，一个动作就是一个 PHP 函数。一个函数要成为一个动作，它需要被注册成一个动作钩子。在上面的部分可以看到什么是动作钩子，但是动作钩子要用作任何目的，需要有个动作为它们注册。这就是插件的来源。你开发的自定义的函数(动作)当动作钩子出发之后就可以执行一个特定任务了。要实现这个，就要使用 add_action() 函数。

  • $tag – 你的函数执行时代动作钩子的名称。
  • $function – WordPress 要调用的函数名。
  • $priority – 一个表示动作调用顺序的整数，默认是10。数字越小，这个函数越早被调用。
  • $accepted_args – 动作钩子要传递给你的函数的参数个数。默认只有一个参数。
  • 
    

  动作钩子并不局限于单个动作。你的插件可以将多个函数添加到一个动作钩子上。其他插件，甚至是 WordPress 核心，经常将多个函数添加到同一个钩子上。

  现在是使用动作钩子的时候了。一个常见的动作钩子是 wp_footer 。它提供给前端用户的 WordPress 模板使用。通常它刚好在前调用。在下面的例子中，将要为 wp_footer 注册一个动作并添加一条自定义信息到 footer。

  WordPress 架设。;
  }
  ?>

  仔细看看上面的代码中如何使用 add_action() 函数的。

  第一个参数是钩子的名字( wp_footer )。第二个参数是要回调的函数 ( boj_example_footer_message )。第三个参数是优先级 ( 100 )。这个函数比起其他钩到 wp_footer 中的函数，会在比较靠后的次序执行。如果设置成1，就较先执行。

  要说明，钩子可能会因为许多原因在 WordPress 执行过程中多次触发。任何添加到这个钩子中的动作每当钩子触发时都会执行一次。

  动作钩子函数

  你已经知道了最基本的两个动作钩子函数怎么使用；do_action() 和 add_action()。WordPress 还有其他类型的与动作钩子相关的函数用于插件开发。

  do_action_ref_array() 函数和 do_action() 函数完成同样的工作，只不过参数传递的方式不同。它并不传递通过附加参数的值来确定的多个参数，而是传递一个包含参数的数组。这个参数数组也是一个必须的参数。这个函数的目的是通过引用传递一个对象给添加到特定钩子的动作(函数)。这意味着这个函数可以不用返回就改变对象本身。
  • $tag – 动作钩子的名字。
  • $args – 要传递给注册到这个钩子的函数的参数的数组。通常，这是一个动作可以改变的对象。

  下面看一个 WordPress 如何调用 do_action_ref_array() 的实例。下面的代码展示了 pre_get_posts 动作钩子。WordPress 在从数据库取得 posts 之前执行这个钩子，使得插件可以改变查询 posts 的方式。

  第一个参数 pre_get_posts 是钩子的名字。第二个参数是从数据库中查询 posts 的参数的数组。这个钩子使你可以执行基于那个参数数组的代码。

  假如你想安装随机的顺序来得到首页的 blog，而不是默认的通过发布时间来得到。你就需要注册一个动作到这个钩子，并改变排序顺序。

   is_home &&empty($query-> query_vars['suppress_filters']))
          $query-> set('rderby','rand');
  }
  ?>

  
  

  remove_action() 可以删除先前添加到一个钩子的动作。代表性的，你可以删除 WordPress 默认添加的动作。要删除一个动作，这个动作必须已经用 add_action() 函数添加了。如果你在动作注册之前执行 remove_action()，那么动作并不会被从钩子中删除。

  如果动作被成功删除，则函数返回 true，否则返回 false。

  参数类似于 do_action()。要成功的从一个钩子中删除一个动作， $tag, $function_to_remove, 和 $priority 必须完全的符合 do_action() 中使用的参数。否则动作不会被溢出，同时 remove_action() 返回 flase。

  我们看一个叫做 rel_canonical 的 WordPress 默认动作。这个动作在 和 元素之间添加一个 canonical 链接。

  要删除这个动作，就要使用 remove_action() 函数。你需要定义 $tag 和 $function_to_rmove 参数。这里你不用添加 $priority 因为先前定义动作的时候没有明确指定优先级。

  WordPress、plugin 或者 theme 添加的任何动作都可以在插件中删除。通常只删除 WordPress 添加的动作。许多默认的动作都定义在 wp-includes/default-filters.php 文件中。通过浏览这个文件你就会明白 WordPress 是如何使用动作钩子的。

  remove_all_actions

  在有些插件中，可能需要删除所有特定 tag 或者 特定 tag + 特定优先级的所有钩子。使用 remove_all_actions() 可以一次删除所有符合条件的动作。

  $priority 参数是可选的，默认是 false。如果你设置了这个参数，那么只有这个优先级的动作会被删除。下面的例子从 wp_head 动作钩子中删除不管任何优先级的动作。

  在使用这个函数的时候必须要小心。其他 plugin 或者 theme 可能添加了你不知道动作。这就可能破坏插件应有的功能。通常应该保持你的代码尽可能的特殊。在大多数情况下，你应该使用 remove_action() 函数来代替。

  有的时候需要确定一个钩子是否包含一些动作，或者一个特定的动作是否已经添加到了钩子里面。has_action() 提供了这些功能。

  has_action() 函数的返回值是 Boolean 或者 一个整型值。如果 $function_to_check 参数为空，那么如果有动作已经添加到了钩子中就返回 true，反之，返回 false。而如果 $function_to_check 设置了，而且这个函数已经添加到了钩子里面，则返回该动作的优先级，否则返回 false。

  下面的例子中，根据 wp_footer 动作钩子中是否有注册的动作来确定显示的信息。

   footer 中已经注册有动作了。
  ';
  else
      echo'
   footer 中还没有注册动作。
  ';
  ?>

  下面看一个 WordPress 核心添加到 wp_footer 中的动作。wp_print_footer_script() 默认注册给这个钩子。

  did_action() 使你的插件可以检查一个动作钩子是否已经被执行，或者记录执行的次数。这也意味着这一次页面的加载过程中有些动作被执行了多次。

  这个参数返回动作已经执行的次数，如果还未执行，返回 false。这个函数的一般用途是判断一个动作钩子是否已经被触发，并执行基于 did_action() 的返回值的代码。

  下面的例子中，如果 plugins_loaded 动作钩子已经被触发，就定义一个 PHP 常量。

  register_activation_hook 和 register_deactivation_hook

  在第二章中已经介绍了这两个函数。

  常用的动作钩子

  WordPress 有许多动作钩子，有一些是很常用的。

  plugins_loaded

  对插件开发者来说，plugins_loaded 动作钩子也许是最重要的动作钩子了。它在大多数 WordPress 文件加载完成之后，并在pluggable 函数和 WordPress 开始执行任何东西之前触发。在大多数的插件中，在这个钩子触发之前，不应该执行其他的代码。plugins_loaded 在所有用户启用的插件都被 WordPress 加载之后执行。这也是在加载过程中插件开发这最早能用到的钩子。

  WordPress 的插件应该在这个钩子中执行安装。其他动作也应该添加到这个钩子的回调函数中。

  下面的例子中，使用前面部分创建的 boj_example_footer_message 动作。要把它添加到钩到 plugins_loaded 钩子中的安装动作中，而不是单独调用它。

  WordPress 架设。;
  }
  ?>

  创建一个安装函数并把它钩到 plugins_loaded 中。这样做就可以确保不会由于特定的 WordPress 函数还没有加载而触发错误。

  init

  init 钩子在大多数的 WordPress 都建立之后。WordPress 同样添加许多内部的功能到这个钩子中，例如 post types 和 taxonomies 的厨厕以及默认 widgets 的初始化。

  因为这时几乎 WordPress 中的所有内容都就绪了，当 WordPress 的所有信息都可用时，你的插件使用这个钩子差不多可以做任何需要的事情了。

  下面的例子中，为用户添加了给 pages 写摘要的功能。这应该在 init 中执行，因为 “page” post type 在这时使用 add_post_type_support() 函数来创建。( 详见 Part-11, “扩展 posts”)

  admin_menu

  admin_menu 钩子在管理员页面加载的时候调用。无论何时你的插件直接在管理页面下工作，你都要用这个钩子来执行你的代码。

  下面的例子添加了一个内容是 BOJ Settings 的 sub-menu 项到 WordPress 管理页面的设置菜单。(详见：Part-7，”插件设置”)

  template_redirect

  template_redirect 动作钩子很有用，因为它是 WordPress 知道用户正在浏览的页面的关键。它在特定的页面选择 theme template 之前执行。在只在网站的前端触发，并不在管理员页面触发。

  当你需要为特定的页面加载代码的时候，这个钩子很有用。

  下面的例子中，仅仅为 singular post 加载一个样式表文件。

  wp_head

  在网站的前端，WordPress 的模板调用 wp_head() 函数，会触发 wp_head 钩子。插件使用这个钩子在 和 标签之间添加 HTML。

  下面的例子中在前端添加一个 meta description。

  ';
  }
  ?>

  有些插件错误的使用了 wp_head 动作钩子来添加 JavaScript 代码，实际上应该使用 wp_enqueue_script() 函数的。( 详见：Part-12，”JavaScript 和 AJAX “)。唯一一种使用这个钩子来添加 JavaScript 的情形是当 JavaScript 代码不在一个单独的文件中时。

  过滤器 Filters

  过滤器钩子和动作钩子有很大的区别。它让你可以控制代码的输出。动作钩子是让你插入代码，而过滤器钩子让你重写 WordPress 传递给钩子的代码。你的函数会对输出进行”过滤”。

  要掌握过滤器钩子的概念，必须首先明白 WordPress 的 apply_filters() 函数是如何工作的。

  • $tag – 过滤器钩子的名字。
  • $value – 传递给任何添加到这个钩子的过滤器的参数。这个函数可以添加任意个额外的 $value 参数传递给过滤器。

  注意：在写一个过滤器的时候 $value 必须返回给 WordPress。

  下面是 WordPress 核心的一个过滤器钩子的例子：

  这个例子中，template_include 是一个过滤器钩子的名字，$template 是一个可以通过注册到这个过滤器钩子的过滤器改变的文件名。

  什么是过滤器？

  一个过滤器是一个注册到过滤器钩子的函数。这个函数最少接受一个参数并在执行完代码后返回那个参数。没有过滤器的过滤器钩子没有任何作用。插件开发者可以通过过滤器钩子改变不同的变量 – 从字符串到多位数组。

  当一个过滤器钩子被 apply_filters() 函数调用时，所有注册到这个钩子的过滤器都会被执行。要添加一个过滤器，使用 add_filter() 函数。

  和动作钩子添加动作类似。$accepted_args 是过滤器函数 $function 接受的参数个数，默认是1。你的函数必须至少接受一个参数并返回。

  可以给一个过滤器钩子添加多个过滤器。同样其他 WordPress 插件也可以给这个钩子添加过滤器。过滤器钩子并不限制给一个钩子。注意：因为每个过滤器都必须返回一个值供其他过滤器使用。如果你的函数没有返回值，那就可能会破坏整个 WordPress 或者其他的插件。

  下面看看 wp_title 过滤器钩子，它是负责页面的