插件 API

来自WordPress中文文档
（重定向自Plugin API）
跳转到： 导航, 搜索

wordpress.org.cn

目录

简介

本文介绍的是一些为 WordPress 插件开发者提供的 API (编程语言接口)，以及如何调用这些接口。

阅读本文之前，请先参考开发一个插件，以便了解一些关于插件的概况和详情。文本着重于“执行挂勾”类的接口，这类接口也被称为“过滤器”(Filters)和“动作”(Actions)，WordPress 正是使用这种接口把插件挂接到系统中的。当然，也可在主题文件里面调用这类接口，请参考：主题函数文件

注意： 本文的内容适用于 WordPress 1.2 或更高版本。对于 1.2 之前的版本，只有通过修改 WordPress 的源代码来对系统进行扩展。

执行挂勾、动作和过滤器

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

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

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

如果要查询 WordPress 中所有的标准的动作和插件，请参考： Adam Brown 的 WordPress 执行挂勾数据库。

函数参考

过滤器函数
动作函数
激活与屏蔽挂勾的函数

动作

动作 (Actions) 是由 WordPress 内部的某些事件所触发的，比如说发表一篇文章、更换主题或者访问后台的某个管理界面，这些都是一件事件的例子。而插件则可以指定某些 PHP 函数来响应这些事件所触发的动作。例如：

  • 修改数据库数据
  • 发送电子邮件
  • 修改即将显示出来的内容

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

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

定义动作响应函数

要在插件中执行动作，就要先在插件文件(必须放到wp-content/plugins下)中定义一个响应动作的 PHP 函数。比如下面的例子，实现的功能是在新文章发布时，通过电子邮件通知好友。

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

} /pre

在大多数的动作会向响应它的函数传递一个参数(根据实际情况可能是文章ID也可能是评论ID)。而有些动作则会传递多个，具体情况请参见文档以及 WordPress 的源代码。当然除了传进来的参数以外，响应的函数还可以调用 WordPress 的全局变量和函数，也可以调用插件自定义的变量和函数。

如果插件中有直接输出结果的指令的话(例如 print 或 echo)，那么输出的内容将根据该动作所执行的时间，出现在页面对应的地方。

注意：在插件内定义函数时，有可能会跟其它的插件或者 WordPress 里面的函数重名，所以在命名前请先参考：避免命名冲突。

挂载进 WordPress

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

pre add_action ( '动作名', '响应函数名', [优先级], [参数数目] ); /pre

参数说明：

tt动作名/tt 
WordPress 所提供的动作名，用于标识在哪个动作发生时，执行响应函数
tt响应函数名/tt 
当动作 tthook_name/tt 发生时需要执行的响应函数的名字。可以是 PHP 标准的函数，或者是 WordPress 内的函数，或者是插件内自定义的函数，例如上述例子中的 tt'email_friends'/tt
tt优先级/tt 
这是一个可选的参数，默认值为10。由于可以把多个函数注册到同一个动作，所以这个参于是用于指定注册到这个动作中的这个函数执行的优先级，数字越小优先级越高，执行得也越早，反之亦然。如果若干个函数以相同的优先级注册到同一个动作，那么执行顺序则是由它们注册的先后顺序所决定。
tt参数数目/tt 
这是一个可选的参数，确认值是1。由于某些动作可能会把多个参数传给响应函数，所以这个有时候需要指定响应函数能接受多少个参数。这个参数是在 1.5.1 版加进去的。

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

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

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

Install and Activate

The last step in getting your action hook to work is to install the file and activate the plugin. The PHP function you wrote and the ttadd_action/tt call must go into a PHP file together, and the PHP file must be installed in the wp-content/plugins directory. Once it is installed, you will need to visit the admin section of WordPress and activate your plugin; see Managing Plugins for more details.

Current Hooks For Actions

See Plugin API/Action Reference for a current list of action hooks in WordPress, and links to previous versions of WordPress.

Filters

Filters are functions that WordPress passes data through, at certain points in execution, just before taking some action with the data (such as adding it to the database or sending it to the browser screen). Filters sit between the database and the browser (when WordPress is generating pages), and between the browser and the database (when WordPress is adding new posts and comments to the database); most input and output in WordPress passes through at least one filter. WordPress does some filtering by default, and your plugin can add its own filtering.

The basic steps to adding your own filters to WordPress (described in more detail below) are:

  1. Create the PHP function that filters the data.
  2. Hook to the filter in WordPress, by calling ttadd_filter/tt
  3. Put your PHP function in a plugin file, and activate it.

Create a Filter Function

A filter function takes as input the unmodified data, and returns modified data (or in some cases, a null value to indicate the data should be deleted or disregarded). If the data is not modified by your filter, then the original data must be returned so that subsequent plugins can continue to modify the value if necessary.

So, the first step in creating a filter in your plugin is to create a PHP function to do the filtering, and put it in your plugin file (your plugin file must go into the wp-content/plugins directory). For example, if you want to make sure that your posts and comments contain no profanity, you might define a global variable with a list of forbidden words, and then create the following PHP function:

pre function filter_profanity($content) { 

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

} /pre

NOTE: Keep in mind that other plugins or the WordPress core may already be using the function name you have thought of. See the Plugin Development Suggestions for more information.

Hook in your Filter

After your function is defined, the next step is to hook or register it with WordPress. To do this, call ttadd_filter/tt in the global execution space of your plugin file:

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

where:

tthook_name/tt 
The name of a filter hook provided by WordPress, which defines when your filter should be applied.
ttyour_filter/tt 
The name of the function that you want to use for filtering. This can be a standard PHP function, a function present in the WordPress core, or a function defined by you in the plugin file.
ttpriority/tt 
An optional integer argument that can be used to specify the order in which the functions associated with a particular filter are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the filter.
ttaccepted_args/tt 
An optional integer argument defining how many arguments your function can accept (default 1), useful because some hooks can pass more than one argument to your function.

In the example above, we would put the following in the main executing section of the plugin file, to tell WordPress to filter comments for profanity:

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

You can also remove filters from filter hooks using the ttremove_filter()/tt function. See Removing Actions and Filters.

Install and Activate

The last step in getting your filter hook to work is to install the file and activate the plugin. The PHP function you wrote and the ttadd_filter/tt call must go into a PHP file together, and the PHP file must be installed in the wp-content/plugins directory. Once it is installed, you will need to visit the admin section of WordPress and activate your plugin; see Managing Plugins for more details.

Current Hooks for Filters

See Plugin API/Filter Reference for a current list of filter hooks in WordPress, and links to previous versions of WordPress.

Example

This is an example, as described by Ozh on the wp-hackers email list, for a plugin to modify (or overwrite) the default codebloginfo()/code function. This will require modifying a core function behavior.

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

Removing Actions and Filters

In some cases, you may find that you want your plugin to disable one of the actions or filters built into WordPress, or added by another plugin. You can do that by calling ttremove_filter('filter_hook','filter_function')/tt or ttremove_action('action_hook','action_function')/tt.

For example, ttremove_action('publish_post','generic_ping');/tt would prevent your weblog from sending pings whenever a new post is created.

Note that if a hook was registered using a priority other than the default of 10, then you must also specify the priority in the call to ttremove_action()/tt. Also note that in general, you shouldn't remove anything unless you know what it does and why it does it -- check the WordPress or other plugin source code to be sure.


Functions You Can Override

Besides the hooks (actions and filters) described above, another way for a plugin to modify WordPress's behavior is to override WordPress functions. In fact, there is a small set of functions that WordPress intends for plugins to redefine. WordPress loads these functions only if they are still undefined after all plugins have been loaded. For more details examine onlyincludecodewp-settings.php/code/onlyinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Template Description

Link to the source code on http://core.trac.wordpress.org/browser/.

Parameters

  1. filename
  2. (option) path to codetag/code (version) or codetrunk/code. This option is only used for a new function.br /Default: codetrunk/code -- trunk is the latest bleeding edge development version of WordPress.

Usage

Link to the stable version: pre检查到模板循环：模板:Trac/pre

Link to trunk: pre检查到模板循环：模板:Trac/pre

/div

wordpress.org.cn file.

These functions are defined in file onlyincludecodewp-includes/pluggable.php/code/onlyinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Template Description

Link to the source code on http://core.trac.wordpress.org/browser/.

Parameters

  1. filename
  2. (option) path to codetag/code (version) or codetrunk/code. This option is only used for a new function.br /Default: codetrunk/code -- trunk is the latest bleeding edge development version of WordPress.

Usage

Link to the stable version: pre检查到模板循环：模板:Trac/pre

Link to trunk: pre检查到模板循环：模板:Trac/pre

/div

wordpress.org.cn. Here is a list for version 2.7.1; documentation for at least some of them can be found in the Function Reference:

来自“http://codex.wordpress.org.cn/index.php?title=%E6%8F%92%E4%BB%B6_API&oldid=143501”
用户
名字空间
变换
操作
导航
WordPress
工具箱