编辑“WordPress:Plugin API”

<span style="border:1px solid #000; text-align:center; float:right; padding:6px;"><strong>导航:</strong> [[WordPress:WordPress文档|上一级]] | [[WordPress]] | {{Template:WordPress导航}}</span>
<div style="clear:both;"></div>
==介绍==
这个网页证明了API（应用程序接口）hooks,WordPress插件开发者可以使用，和怎样使用这些。

这篇文章假定你已经阅读了[[WordPress:Writing a Plugin|写一个插件]]，这个给出了怎样发表一个插件的梗概（和许多详细信息）。这篇文章是明确关于"Hooks"的API，也称为"过滤器" 和"Actions",WordPress用这个将你的插件设置为运转之中。

注：这个信息适用于WordPress1.2版本以及更高的版本。在1.2版本之前，修改被称为是"hacks"并且涉及到编辑WordPress自身的源代码。

== Hooks, Actions 和过滤器 ==
Hooks是由WordPress提供的，使你能够插入'hook into'WordPress的其余部分；这就是说，在特别时间里，访问你的插件里的函数，这样就将你的插件设置为运转的了。有两种类型的hooks：

# [[#WordPress:Actions|Actions]]:Actions是hooks，在执行的时候，或者当一个特别的事件发生的时候，WordPresshe核心发行在一个特殊的点上。你的WordPress可以指定它的一个或者更多的PHP函数在这些点的时候执行，使用Action API。

# [[#WordPress:Filters|过滤器]]:过滤器是hooks，WordPress发行来更改不同类型的文本，在WordPress将文本添加到数据库或者将它发送到浏览器界面之前，添加。你的插件可以指定它的一个或者更多的PHP函数被执行用来在这些时候修改特别类型的文本，使用过滤器API。

有时候你可以使用一个action或者一个过滤器达到同样的目标。例如，如果你想要你的插件来更改一篇文章的文本，你可能添加一个action函数到<tt>publish_post</tt>（这样文章便被修改了，因为文章已经保存到了数据库），或者添加一个过滤器到<tt> _内容</tt>（这样文章便被更改了，因为文章显示在浏览器界面）。

== Actions ==

'''Actions'''是由发生在WordPress里的特殊事件触发的，例如发表一篇文章，更改主题，或者显示管理面板的一个页面。通过执行一个PHP函数，你的插件可以对事件做出回应，可能会执行以下一个或者更多的步骤：
*更改数据库数据

*发送一个电子邮件信息

*更改显示在浏览器屏面上的内容（管理或者最终用户）

使这个发生的基本步骤是（在下面有更加详细的描述）：
#创建PHP函数，这个函数在事件发生的时候，会在你的插件文件中执行。
#通过访问<tt>add_action</tt>，hook到WordPress中的action
#将你的PHP函数放入一个插件文件中，然后将它激活。

===创建一个 Action 函数 ===
在你的插件中创建一个action的第一个步骤就是用你的插件泛函性创建一个PHP函数，并且将这个函数放入你的插件文件（你的插件文件必须进入''wp-content/插件''目录）。例如，当你写了一篇新的文章的时候，你想让你的朋友得到一个电子邮件的关于你的文章的信息，你可能会定义以下的函数：
<pre>
function email_friends($post_ID)  {
  $friends = 'bob@example.org,susie@example.org';
    mail($friends, "sally's blog updated", 
      '我只是在博客上写了一些东西: http://blog.example.com');
    return $post_ID;
}
</pre>

对于大多数actions，你的函数应该接受一个单一的参数（通常是文章或者评论ID，这取决于action）。有的action不止需要一个参数—查看文件中的action(如果拥有的话)或者WordPress源代码得到更多的信息。除了一个参数以外，你可以访问WordPress的全局变数，和其它的WordPress函数（或者你的插件文件的函数）。

'''注''':  ；牢记其它的插件或者WordPress核心可能已经在使用你想到的函数名。更多的信息，请看[[WordPress:Writing a Plugin#Avoiding Function Name Collisions|避免函数名重叠]]。
=== Hook to WordPress ===
定义你的函数之后，第二步就是"hook"或者将它注册到WordPress。要这样做，要做到这一点，在你的插件文件的全局执行空间中访问<tt>add_action()</tt>。

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

</pre>
 
这儿是：

* <tt>hook_name</tt>是WordPress提供的一个action hook，描述了你的函数应该与哪个活动联合。

*<tt>your_function_name</tt>是函数名，你想根据<tt>hook_name</tt>规定的活动，执行后纵隔函数。这可以是一个标准的php函数，显现在WordPress核心的函数，或者是一个你在插件文件中定义的函数（例如上述定义的<tt>'email_friends'</tt>）。

* <tt>priority</tt>是一个任意的整数论点，可以用来规定函数与一个特别的action 执行的顺序（默认值是：10）。更小的数字与更早的执行相符合，有着同样的优先权的函数，执行是按它们添加到action的顺序。

* <tt>accepted_args</tt>是一个任意的整数引数规定了你的函数可以接受多少个引数（默认为1），这很有用，因为有的hooks可以通过几个引数到达你的函数。这个参数在1.5.1版本中是新的。

在上述的例子中，我们会将下面的行放到插件文件中：

<pre>
add_action('publish_post', 'email_friends');
</pre>

同样地，你也可以从action hooks中[[#WordPress:Removing Actions and Filters|移除 Actions]]。详细信息请看那个部分。

=== 安装和激活 ===

使你的action hook运行的最后的一个步骤就是安装文件并且激活那个插件。你所写的和<tt>add_action</tt>访问必须一同地进入一个PHP文件，PHP文件必须安装在''wp-content/plugins''目录。
一旦PHP文件安装了，你就要访问WordPress的管理部分并且激活你的插件；更多详细信息请看[[WordPress:Managing Plugins|管理插件]]。

=== 关于Actions的当前的Hooks ===

请查看[[WordPress:Plugin API/Action Reference]]得到WordPress里的action hooks的一个当前的列表以及链接到先前版本的WordPress的链接。

== 过滤器 ==

'''过滤器'''是WordPress，在执行时的某一点上，就在用数据采取一些活动之前，通过数据的函数（例如将它添加到数据库或者将它发送到浏览器界面）。过滤器在数据库和浏览器之间（当WordPress产生网页的时候），在浏览器和数据库之间（当WordPress给数据库添加新的文章和评论的时候）；WordPress中大多数输入和输出至少通过一个过滤器。默认情况下，WordPress处理一些过滤，而且你的插件可以添加它自己的过滤。

将你自己的过滤器添加到WordPress的基本步骤是（在下面详细描述了）：
#创建过滤了数据的PHP函数。
#通过访问<tt>add_filter</tt>，hook到WordPress里的过滤器。
#将PHP函数放到一个插件文件中，并且将它激活。

=== 创建一个过滤器函数 ===

一个过滤器函数用来输入未修改的数据，并且返回修改的数据(或者在有些情况下，一个null值暗示数据应该被删除或者忽视)。如果数据没有被你的过滤器修改，那么原始的数据必须返回，这样如果需要的话，随后的数据会继续修改值。

因此，在你的插件上创建一个过滤器的第一步便是创建一个PHP函数来做过滤，并把这个函数放入你的插件文件（而且你的插进文件必须进入''wp-content/插件''目录）。例如，如果你想确定你的文章和评论没有包含任何亵渎的内容，你可能要用一列禁语定义一个全局变量，然后创建下面的PHP函数：

<pre>
function filter_profanity($content) {
    global $profanities;
    foreach($profanities as $profanity) {
        $content=str_ireplace($profanity,'{censored}',$content);
    }
    return $content;
}
</pre>

'''注''':牢记其它的插件或者WordPress核心可能已经正在使用你已经想到的函数名。更多的信息请看[[WordPress:Writing a Plugin#Avoiding Function Name Collisions|避免函数名重叠]]。
=== 你的过滤器的Hook ===

在你的函数得到定义之后,下一步就是将它"hook"或者注册到WordPress。要做到这一点，在你的插件文件的全局执行空间访问<tt>add_filter</tt>：

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

</pre>

这儿有：

* <tt>hook_name</tt>是一个过滤器hook的名称，由WordPress提供，定义了什么时候应该使用你的过滤器。

*<tt>你的_过滤器</tt>是你想用来过滤的函数名。这可能是一个标准的PHP函数，一个显示在WordPress核心的函数，或者一个你定义在插件文件中的函数。

* <tt>priority</tt>是一个随意的整型参数，可以用来规定函数一个特别的过滤器执行的顺序（默认：10）更低的数字符合更早的执行，拥有同样的优先权的函数执行的顺序，是它们添加到过滤器的顺序。

* <tt>accepted_args</tt>是一个任意的整型参数，定义你的函数可以接受多少参数（默认1），有用，因为有的hooks可以通过不止一个参数到你的函数上。

在上述的例子中，我们会将以下的内容放到插件文件的主要执行区域，指示WordPress为防止亵渎，而过滤评论：

<pre>
add_filter('comment_text','filter_profanity');
</pre>

你也可以使用WordPress函数<tt>remove_filter()</tt>将过滤器从过滤器hooks中移除。请看看[[#WordPress:Removing Actions and Filters|移除 Actions 和过滤器]]。

=== 安装和激活 ===

使你的过滤器hook运行的最后一步便是安装文件并且激活插件。你写的PHP函数和<tt>add_filter</tt>调用必须一同地进入一个PHP文件，而且PHP文件必须安装在''wp-content/plugins''目录。一旦这个文件安装了，你就要访问WordPress的管理部分并且激活你的插件；更多的信息请看看[[WordPress:Managing Plugins|管理你的插件]]。
=== 过滤器的当前的Hooks ===

请看[[WordPress:Plugin API/过滤器参考]]中WordPress当前过滤器hooks的列表，和链接到先前版本WordPress的链接。
=== 例子 ===

这是一个例子，[http://comox.textdrive.com/pipermail/wp-hackers/2008-February/018013.html 如Ozh 在 wp-hackers电子邮件列表上所描述的]

<pre>
add_filter('bloginfo', 'mybloginfo', 1, 2);
add_filter('bloginfo_url', 'mybloginfo', 1, 2);

function mybloginfo($result='', $show='') {
        switch ($show) {
        case 'wpurl':
                $result = SITE_URL;
                break;
        case 'template_directory':
                $result = TEMPL_DIR;
                break;
        default: 
        }
        return $result;
}
</pre>

== 移除Actions 和过滤器 ==

有的情况下，你可能发现你想要你的插件取消WordPress建的其中的一个actions或者过滤器，或者添加另一个插件。通过访问<tt>remove_filter('filter_hook','filter_function')</tt> 或者<tt>remove_action('action_hook','action_function')</tt>，你便可以做到这一点。

例如，<tt>remove_action('publish_post','generic_ping');</tt>会防止你的博客在产生一篇新的文章的时候，发送pings。

注意如果一个hook已经注册了，使用一个优先而不是默认的10，那么你也必须规定命令中的优先为<tt>remove_action()</tt>。同时注意，一般情况下，你不应该移除任何东西，除非你知道你移除的东西是执行什么的以及它为什么会执行—查看WordPress或者其它插件的源代码以得到确切答案。

==默认使用的过滤器和Actions ==

找到WordPress默认使用的过滤器和actions的最可靠的方法便是在WordPress核心文件中搜索<tt>add_filter</tt> 和<tt>add_action</tt>。
=== WordPress 2.1 ===

在WordPress2.1中，大多数的默认的过滤器和actions都是从文件<tt>wp-includes/default-filters.php</tt>上添加的。一些其它的是在以下的这些文件中：

* <tt>wp-admin/admin-ajax.php</tt>
* <tt>wp-admin/admin-functions.php</tt>
* <tt>wp-admin/custom-header.php</tt>
* <tt>wp-admin/edit.php</tt>
* <tt>wp-admin/index.php</tt>
* <tt>wp-admin/options-permalink.php</tt>
* <tt>wp-admin/upload-functions.php</tt>
* <tt>wp-admin/upload.php</tt>
* <tt>wp-includes/bookmark.php</tt>
* <tt>wp-includes/general-template.php</tt>
* <tt>wp-includes/kses.php</tt>
* <tt>wp-includes/plugin.php</tt>
* <tt>wp-includes/rewrite.php</tt>
* <tt>wp-includes/template-loader.php</tt>
* <tt>wp-includes/theme.php</tt>

大多数默认的过滤器和actions都添加在WordPress1.5中的<tt>wp-includes/default-filters.php</tt>中。


== 你可以搞定的函数==

除了以上所描述的hooks（actions和过滤器），一个插件修改WordPress的执行的另一种方法就是搞定WordPress函数。事实上，有一些函数WordPress打算让插件来重新定义。只有所有的插件都载入后，这些函数还都没有定义的情况下，WordPress才会载入这些，来利用这个。

这些函数定义在文件<tt>wp-includes/pluggable.php</tt>中。这里有一个列表（目前是2.1版本的）；其中的一些文件可以在[[WordPress:Function Referenc|函数参考]]中找到：

* <tt>set_current_user</tt>
* <tt>wp_set_current_user</tt>
* <tt>wp_get_current_user</tt>
* <tt>get_currentuserinfo</tt>
* <tt>get_userdata</tt>
* <tt>update_user_cache</tt>
* <tt>get_userdatabylogin</tt>
* <tt>wp_mail</tt>
* <tt>wp_login</tt>
* <tt>is_user_logged_in</tt>
* <tt>auth_redirect</tt>
* <tt>check_admin_referer</tt>
* <tt>wp_redirect</tt>
* <tt>wp_get_cookie_login</tt>
* <tt>wp_setcookie</tt>
* <tt>wp_clearcookie</tt>
* <tt>wp_notify_postauthor</tt>
* <tt>wp_notify_moderator</tt>
* <tt>wp_new_user_notification</tt>
* <tt>wp_verify_nonce</tt>
* <tt>wp_create_nonce</tt>
* <tt>wp_salt</tt>
* <tt>wp_hash</tt>