WordPress:Plugin API

来自站长百科
跳转至： 导航、​ 搜索

导航: 上一级 | WordPress | 首页 | WordPress中文论坛 | WordPress主机 | CMS程序 | 论坛程序 | ECShop | ShopNC | PowerEasy

介绍[ ]

这个网页证明了API（应用程序接口）hooks,WordPress插件开发者可以使用，和怎样使用这些。

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

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

Hooks, Actions 和过滤器[ ]

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

  1. Actions:Actions是hooks，在执行的时候，或者当一个特别的事件发生的时候，WordPresshe核心发行在一个特殊的点上。你的WordPress可以指定它的一个或者更多的PHP函数在这些点的时候执行，使用Action API。
  1. 过滤器:过滤器是hooks，WordPress发行来更改不同类型的文本，在WordPress将文本添加到数据库或者将它发送到浏览器界面之前，添加。你的插件可以指定它的一个或者更多的PHP函数被执行用来在这些时候修改特别类型的文本，使用过滤器API。

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

Actions[ ]

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

  • 更改数据库数据
  • 发送一个电子邮件信息
  • 更改显示在浏览器屏面上的内容（管理或者最终用户）

使这个发生的基本步骤是（在下面有更加详细的描述）：

  1. 创建PHP函数，这个函数在事件发生的时候，会在你的插件文件中执行。
  2. 通过访问add_action，hook到WordPress中的action
  3. 将你的PHP函数放入一个插件文件中，然后将它激活。

创建一个 Action 函数[ ]

在你的插件中创建一个action的第一个步骤就是用你的插件泛函性创建一个PHP函数，并且将这个函数放入你的插件文件（你的插件文件必须进入wp-content/插件目录）。例如，当你写了一篇新的文章的时候，你想让你的朋友得到一个电子邮件的关于你的文章的信息，你可能会定义以下的函数： 

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;
}

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

注: ；牢记其它的插件或者WordPress核心可能已经在使用你想到的函数名。更多的信息，请看避免函数名重叠。

Hook to WordPress[ ]

定义你的函数之后，第二步就是"hook"或者将它注册到WordPress。要这样做，要做到这一点，在你的插件文件的全局执行空间中访问add_action()。 

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

这儿是：

  • hook_name是WordPress提供的一个action hook，描述了你的函数应该与哪个活动联合。
  • your_function_name是函数名，你想根据hook_name规定的活动，执行后纵隔函数。这可以是一个标准的php函数，显现在WordPress核心的函数，或者是一个你在插件文件中定义的函数（例如上述定义的'email_friends'）。
  • priority是一个任意的整数论点，可以用来规定函数与一个特别的action 执行的顺序（默认值是：10）。更小的数字与更早的执行相符合，有着同样的优先权的函数，执行是按它们添加到action的顺序。
  • accepted_args是一个任意的整数引数规定了你的函数可以接受多少个引数（默认为1），这很有用，因为有的hooks可以通过几个引数到达你的函数。这个参数在1.5.1版本中是新的。

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

add_action('publish_post', 'email_friends');

同样地，你也可以从action hooks中移除 Actions。详细信息请看那个部分。

安装和激活[ ]

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

关于Actions的当前的Hooks[ ]

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

过滤器[ ]

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

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

  1. 创建过滤了数据的PHP函数。
  2. 通过访问add_filter，hook到WordPress里的过滤器。
  3. 将PHP函数放到一个插件文件中，并且将它激活。

创建一个过滤器函数[ ]

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

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

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

注:牢记其它的插件或者WordPress核心可能已经正在使用你已经想到的函数名。更多的信息请看避免函数名重叠。

你的过滤器的Hook[ ]

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

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

这儿有：

  • hook_name是一个过滤器hook的名称，由WordPress提供，定义了什么时候应该使用你的过滤器。
  • 你的_过滤器是你想用来过滤的函数名。这可能是一个标准的PHP函数，一个显示在WordPress核心的函数，或者一个你定义在插件文件中的函数。
  • priority是一个随意的整型参数，可以用来规定函数一个特别的过滤器执行的顺序（默认：10）更低的数字符合更早的执行，拥有同样的优先权的函数执行的顺序，是它们添加到过滤器的顺序。
  • accepted_args是一个任意的整型参数，定义你的函数可以接受多少参数（默认1），有用，因为有的hooks可以通过不止一个参数到你的函数上。

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

add_filter('comment_text','filter_profanity');

你也可以使用WordPress函数remove_filter()将过滤器从过滤器hooks中移除。请看看移除 Actions 和过滤器。

安装和激活[ ]

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

过滤器的当前的Hooks[ ]

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

例子[ ]

这是一个例子，如Ozh 在 wp-hackers电子邮件列表上所描述的 

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;
}

移除Actions 和过滤器[ ]

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

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

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

默认使用的过滤器和Actions[ ]

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

WordPress 2.1[ ]

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

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

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


你可以搞定的函数[ ]

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

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

  • set_current_user
  • wp_set_current_user
  • wp_get_current_user
  • get_currentuserinfo
  • get_userdata
  • update_user_cache
  • get_userdatabylogin
  • wp_mail
  • wp_login
  • is_user_logged_in
  • auth_redirect
  • check_admin_referer
  • wp_redirect
  • wp_get_cookie_login
  • wp_setcookie
  • wp_clearcookie
  • wp_notify_postauthor
  • wp_notify_moderator
  • wp_new_user_notification
  • wp_verify_nonce
  • wp_create_nonce
  • wp_salt
  • wp_hash
取自“https://www.zzbaike.com/wiki/WordPress:Plugin_API?oldid=3393”