编辑“WordPress:Writing a Plugin”

= 介绍 =

WordPress 1.2版本之前，如果你想要修改WordPress行为，你必须编辑(或者 "hack") WordPress 源代码。尽管如此，在更多的现行WordPress版本中 ，你可以通过使用[[WordPress:Plugins|插件]]很容易的修改添加核心功能。基本的插件结构的想法是保持WordPress核心相关内容的简洁，但是富有灵活性，足以使各个输入输出方面可以通过插件来修改。下面是定义:

;WordPress 插件 : WordPress 插件是一个程序，或者是一组或更多函数，由PHP脚本语言编写，添加某种特殊的功能或者服务到WordPress weblog，使用接入点和WordPress [[WordPress:Plugin API|Plugin Application Program Interface (API)]] 提供的方法，可以与weblog很好的结合在一起。 

如果你发现你希望WordPress能拥有一些新的或者改良的功能，第一件事就是搜索各种插件库(你可以从 [[WordPress:Plugins|插件]]文章中了解)，然后看是否某人已经创建了这样的适合你的需要的插件。如果没有，本文将指导你如何创建你自己的插件的过程。

本文假设你已经熟悉基本的WordPress功能以及 PHP编程。
== 资源 ==

* 有很多插件开发者的的全面的文章列表和资源，[[WordPress:Plugin Resources|插件资源]]中包括有关编写插件的外部文章以及关于特别话题的文章。
* 另外一个了解有关插件的好方法是看写的好的插件的PHP 源代码，如 [[WordPress:Plugins#Default Plugins|Hello Dolly]], 一个分布式插件。 
* 一旦你写了插件，阅读[[WordPress:Plugin Submission and Promotion|插件提交和宣传]]来学习如何让它更广泛的散布开来。

= 创建插件 =

本部分进入你需要遵守的几个步骤，和一些考虑什么时候建立一个结构良好的 WordPress插件。

== 名字，文件和位置 ==

=== 插件名字 ===

创建插件的第一个任务是想出插件要做什么，然后起一个(希望是唯一的)名字。 查看[[WordPress:Plugins|插件]] 和其他的相关库，验证你的名字是唯一的；你也可以使用Google搜索。 多数插件开发者选择使用能描述插件功能的那个名字; 如，一个联系到天气的插件可能含有单词"weather"在名字中。名字可以是好几个词。

=== 插件文件 ===

下一步是创建PHP文件，文件名由你选择的插件名衍生而来。如，如果你的插件叫做"Fabulous Functionality"，你可以把你的PHP文件起名为 <tt>fabfunc.php</tt>。试着取一个唯一的名字。人们安装你的插件的时候会把这个PHP文件放到WordPress插件目录中，<tt>wp-content/plugins/</tt>，所以没有两个不同的在使用的插件拥有相同的PHP文件名。 

另外一个操作是把你的插件分成几个文件，你的插件至少要有一个PHP 文件，它可以包含JavaScript文件，CSS文件，图片文件和语言文件等等。如果有几种文件选择了唯一的文件夹和主PHP文件名字，如<tt>fabfunc</tt> 和 <tt>fabfunc.php</tt>，就把所有的插件文件放到这个目录下，然后告诉你的插件用户安装整个目录到<tt>wp-content/plugins/</tt>下。

在这个文章的其余部分，"插件PHP文件"引用了主插件PHP文件，可以在 <tt>wp-content/plugins/</tt> 或者一个子目录下

=== 自述文件 ===

如果你想在http://wordpress.org/extend/plugins/上建立一个插件主机，你还需要用标准格式创建<tt>readme.txt</tt>文件，把它放到你的插件中去。参见 http://wordpress.org/extend/plugins/about/readme.txt 获得这格式的描述.

=== 主页 ===

创建一个网页来作为你的插件的主页也是非常有用的。这个页面可以描述如何安装插件，它可以做些什么，兼容WordPress 的哪个版本，版本更替的时候你的插件做出了哪些改动，如何使用插件等等。

== 文件标题 ==

现在开始在你的插件的主PHP文件中添加信息。

=== 标准插件信息 ===

插件主PHP文件的顶部必须包含一个标准插件信息标题。这个标题让WordPress 识别你的插件存在，添加到插件管理界面以便激活，载入，运行; 没有标题，你的插件将不会被激活也不会运行，如下是标题格式：

<pre>
<?php
/*
Plugin Name: Name Of The Plugin
Plugin URI: http://URI_Of_Page_Describing_Plugin_and_Updates
Description: A brief description of the plugin.
Version: The plugin's Version Number, e.g.: 1.0
Author: Name Of The Plugin Author
Author URI: http://URI_Of_The_Plugin_Author
*/
?>
</pre>

WordPress需要用来识别你的插件的最小信息是Plugin Name这行，其他信息(如果出现的话) 将用来创建插件管理界面上的插件表格。这些行的顺序并不重要。

=== 许可 ===

根据带有许可信息这个标准标题是个惯例。多数插件使用WordPress 使用的[http://www.gnu.org/copyleft/gpl.html GPL] 许可，或者是一个 [http://www.fsf.org/licensing/licenses/index_html#GPLCompatibleLicenses compatible with the GPL]的许可。简要说明下GPL许可，在你的插件中添加如下几行:

<pre>
<?php
/*  Copyright YEAR  PLUGIN_AUTHOR_NAME  (email : PLUGIN AUTHOR EMAIL)

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/
?>
</pre>

== 规划你的插件 ==

现在是该让你的插件做些什么的时候了。这个部分包含了一些一般的关于插件开发的思想，描述了如何完成你的插件需要完成的几个任务。

=== WordPress 插件 Hooks ===

很多插件通过连接一个或者多个的WordPress 插件 "hooks"来完成它们的目标。 插件hooks的工作方式是在WordPress运行的时候，在各个不同的时候，WordPress检查是否有插件在那时有注册过的函数在此刻运行，如果有的话，函数运行。三个函数更改WordPress的默认行为。

例如，在WordPress添加文章标题到浏览器输出的时候，首先检查是否有任何插件为"filter"hook注册了一个函数叫做"the_title"。如果有，标题文字会被每个注册函数按顺序传递，最终结果就是打印出来的结果。这样，如果你的插件需要添加一些信息到打印标题，它可以注册一个"the_title" filter函数.

另一个例子是"action" hook，叫做"wp_footer"。在WordPress生成的HTML页面的底部，它检查看是否某个插件已经为 "wp_footer" action hook注册函数，然后依次运行。

你可以了解更多关于如何为filter 和 action hooks注册函数，什么插件hooks在WordPress和在[[WordPress:Plugin API|插件API]]中可用。如果你在WordPress代码中发现一个你想使用action或者filter的地方，但是WordPress没有，你可以建议使用新的hooks (建议通常都会被采纳); 如何建议参见[[WordPress:Reporting Bugs|提交错误]]。

=== 模板标签 ===

另外一种用插件添加WordPress功能的方法是通过建立自定义 [[WordPress:Template Tags|模板标签]]。有人想使用你的插件添加这些 "标签"到他们的主题，边栏，文章目录或者其他任何合适的地方。例如，添加地理标签到文章中的插件，可以为边栏定义一个叫做<tt>geotag_list_states()</tt>的模板标签函数，列出所有的有关国家，并带有国家归档页面的链接。

想要定义一个模板标签，需要简单的写一个PHP 函数并为插件用户在插件主页或者是插件PHP主文件中写下资料说明。在给函数做资料说明时，给出一个具体需要加入什么到主题文件中以使用函数的例子是个不错的想法包括 <tt><?php</tt> 和 <tt>?></tt>.

===保持插件数据到数据库===

大多数插件需要从站长或者blog用户得到一些信息并保存在sessions中，为了在它的filter 函数, action 函数和模板函数中使用。这个信息必须保存在WordPress 数据库中，为了在sessions中可以持久稳定。有两种基本方法可以保存插件数据到数据库中:
# 使用WordPress "操作"机制(下有描述)。这个方法适合储存相关的小量静态的指定的数据 – 那种你希望在第一次设置插件时站长输入的，今后几乎不会更改的数据。
# 创建一个新的自定义的数据库表格。这种方法适合联合单独的文章，页面，附件或者评论的数据—一种随着时间而增加的，没有单独的名字的数据。参见 [[WordPress:Creating Tables with Plugins|创建插件表格]].

=== WordPress 操作机制===

参见[[WordPress:Creating Options Pages|创建操作页面]] 得到关于如何创建自动为你保存操作的页面的信息。

WordPress有一个保存，更新，重新得到个体， 制定的数据("操作")机制，在 WordPress 数据库中。操作值可以是字符串，数组或者是PHP对象(它们将被 "连载"，或者在存储前转变为字符串，在重新得到个体时反连载)。操作名字是字符串，它们必须是唯一的，这样它们不会与其他 WordPress或者是插件起冲突。

这里是你的插件可以用来进入WordPress操作的主要函数。

<pre>
add_option($name, $value, $description, $autoload);
</pre>
: 创建一个新选项;如果选项存在就什么都不做
;$name: Required (string). 将被添加的选项名字
;$value: Optional (string), 默认为空的字符串。 将被存储的选项值
;$description: Optional (string), 默认为空的字符串。选项的描述，被放在wordpress数据库中以防某些人浏览数据库去看选项在哪。
;$autoload: 选项，默认为'yes' (enum: 'yes' or 'no').如果设置为'yes',那么设置被<tt>get_alloptions</tt>函数自动检索。
<pre>
get_option($option);
</pre>
: 从数据库中检索一个选项值
;$option: Required (string).  你想要返回的选项值的选项的名称。你能够找到被安装在[[WordPress:Option Reference|相关选项]]中的一列默认选项
<pre>
update_option($option_name, $newvalue);
</pre>
: 在数据库里更新或者创建一个选项值（注：如果你不想使用<tt>$description</tt> 或者 <tt>$autoload</tt>参数，<tt>add_option</tt>就没必要被访问。)
;$option_name: Required (string). 选项名称更新。
;$newvalue: Required.  为选项赋予新的值。

=== 管理面板 ===

假设你的插件有一些操作存储在WordPress数据库中 (参见上面的部分)，你也许希望有一个管理面板，允许你的插件用户来查看和编辑操作。方法可以在 [[WordPress:Adding Administration Menus|添加管理目录]]中找到。
== 让你的插件国际化 ==

一旦你插件的程序完成了，另一个需要考虑的是(假设你打算发布你的插件) ''国际化''. 国际化是建立软件的一个过程，这样它才可以''本地化'' ；本地化是翻译软件的显示文本为其他语言。WordPress是全世界使用的，所以它有国际化和本地化版本，包括本地化的插件。想要知道关于WordPress的 GNU gettext的本地化使用，参见[[WordPress:Translating WordPress]]. 

It is highly recommended that you internationalize your plugin, so that users from different countries can localize it. The process is fairly straightforward:
* Choose a translation "text domain" name for your plugin. This is generally the same as your plugin file name (without the <tt>.php</tt>), and must be unique among plugins the user has installed.
* Wherever your plugin uses literal text strings that will be displayed to the user (known as "messages"), wrap them in one of the two WordPress gettext functions. Note that in a plugin, you need to use the second argument, passing in the translation text domain name you chose, unlike in the core of WordPress (which leaves the <tt>$domain</tt> argument blank).
; <tt>__($message, $domain)</tt> : Translates <tt>$message</tt> using the current locale for <tt>$domain</tt>. Wrap text strings that you are going to use in calculations with this function.
; <tt>_e($message, $domain)</tt> : Translates <tt>$message</tt> using the current locale for <tt>$domain</tt>, and then prints it on the screen. Wrap text strings that you are directly printed with this function.

强力推荐你国际化你的插件，这样来自不同国家的用户，可以本地化插件，过程如下:
* 给插件选择一个翻译"文本区域"名字。这通常和你的插件文件名字一样(除了 <tt>.php</tt>), 而且必须是用户安装过的插件中唯一的。
* 不论在哪里插件使用的显示给用户的文本(即"消息"), 使用一个或者两个 WordPress gettext 函数把它们包围起来。注意在插件中，你需要使用第二种方法，你选择的翻译文本区域名字中的传递，不像WordPress核心(留下 <tt>$domain</tt> 这部分空白).
; <tt>__($message, $domain)</tt> :使用现有本地<tt>$domain</tt>翻译 <tt>$message</tt>。换行你将要用来用这个函数计算的文字字符串。
; <tt>_e($message, $domain)</tt> : 使用现有本地<tt>$domain</tt>翻译 <tt>$message</tt>, 然后在屏幕上显示出来，换行你使用这个函数直接显示出的文本字符串。

* Create a POT file (translation catalog listing all the translatable messages) for your plugin, and distribute it with your plugin. Users will need to put their translated MO file in the same directory as your plugin's PHP file, and name it <tt>domain-ll_CC.mo</tt>, where <tt>ll_CC</tt> is the name of their locale. See [[WordPress:Translating WordPress]] for information on POT files, MO files, and locales.
* Load the translations for the current locale and your text domain by calling <tt>load_plugin_textdomain</tt> before either of the gettext functions is called, but as late as possible in the session (because some multi-lingual plugins change the locale when they load). One possible implementation is to define an initialization function that is called at the top of all of your plugin functions. For instance, assuming your text domain is "fabfunc":
<pre>
$fabfunc_domain = 'fabfunc';
$fabfunc_is_setup = 0;

function fabfunc_setup()
{
   global $fabfunc_domain, $fabfunc_is_setup;

   if($fabfunc_is_setup) {
      return;
   } 

   load_plugin_textdomain($fabfunc_domain, 'wp-content/plugins');
}
</pre>
If your plugin is in its own subdirectory, append that to the second argument of <tt>load_plugin_textdomain</tt>.

* 创建一个POT文件(翻译目录列出了所有的可以翻译的信息)，随着你的插件分发出去。用户将需要把他们的翻译过的MO文件放在你的插件的PHP文件的同一目录下，命名为<tt>domain-ll_CC.mo</tt>，那里<tt>ll_CC</tt>是本地文件的名字。参见[[WordPress:Translating WordPress|翻译WordPress]]以获得关于POT文件，MO文件和本地文件的信息。
* 通过在调用gettext函数之前调用<tt>load_plugin_textdomain</tt>为现有本地文件和你的文本区域文件载入翻译，在session中越晚越好，(因为一些多语言插件载入时改变了本地文件)。一个可能的办法是定义一个初始化函数，在所有插件函数之前调用，如，假设你的文本区域是"fabfunc":
<pre>
$fabfunc_domain = 'fabfunc';
$fabfunc_is_setup = 0;

function fabfunc_setup()
{
   global $fabfunc_domain, $fabfunc_is_setup;

   if($fabfunc_is_setup) {
      return;
   } 

   load_plugin_textdomain($fabfunc_domain, 'wp-content/plugins');
}
</pre>
If your plugin is in its own subdirectory, append that to the second argument of <tt>load_plugin_textdomain</tt>

If you are reading this section because you want to internationalize a Theme, you can basically follow the steps above, except:
* The MO file goes into the theme directory (same place as style.css).
* The MO file is named <tt>ll_CC.mo</tt>, where <tt>ll_CC</tt> is the name of the locale (i.e. the domain is NOT part of the file name).
* To load the text domain, put the following (inside a PHP escape if necessary) in your theme's functions.php file:
<pre>
load_theme_textdomain('your_domain');
</pre>

如果你阅读了这个部分因为你想要国际化一个主题，你大体上可以按照上面的步骤来，除非:
* MO文件在主题目录中(与style.css同样的位置).
* MO 文件命名为<tt>ll_CC.mo</tt>, <tt>ll_CC</tt>是本地文件名(这个域不是文件名字的一部分).
* 想要载入文本域，加入如下代码(在某个PHP 溢出，如果需要的话) 到你的主题的functions.php文件:
<pre>
load_theme_textdomain('your_domain');
</pre>

= Plugin Development Suggestions =

This last section contains some random suggestions regarding plugin development. 

* The code of a plugin should follow the [[WordPress:WordPress Coding Standards]]. Please consider the [[WordPress:Inline Documentation]] Standards as well.
* All the functions in your plugin need to have unique names that are different from functions in the WordPress core, other plugins, and themes. For that reason, it is a good idea to use a unique function name prefix on all of your plugin's functions. Another possibility is to define your plugin functions inside a class (which also needs to have a unique name).
* Do not hardcode the WordPress database table prefix (usually "wp_") into your plugins.  Be sure to use the <tt>$wpdb->prefix</tt> variable instead. 
* Database reading is cheap, but writing is expensive. Databases are exceptionally good at fetching data and giving it to you, and these operations are (usually) lightning quick.  Making changes to the database, though, is a more complex process, and computationally more expensive.  As a result, try to minimize the amount of <em>writing</em> you do to the database.  Get everything prepared in your code first, so that you can make only those write operations that you need.
* SELECT only what you need. Even though databases fetch data blindingly fast, you should still try to reduce the load on the database by only selecting that data which you need to use.  If you need to count the number of rows in a table don't <tt>SELECT * FROM</tt>, because all the data in all the rows will be pulled, wasting memory.  Likewise, if you only need the post_id and the post_author in your plugin, then just <tt>SELECT</tt> those specific fields, to minimize database load. Remember: hundreds of other processes may be hitting the database at the same time.  The database and server each have only so many resources to spread around amongst all those processes.  Learning how to minimize your plugin's hit against the database will ensure that your plugin isn't the one that is blamed for abuse of resources.

= 插件开发建议 =

最后一部分包括一些关于插件开发的建议。

* 插件代码应该遵循[[WordPress:WordPress Coding Standards| WordPress编码标准]]。请参照[[WordPress:Inline Documentation|内嵌文档]]标准。
* 所有的插件中的函数需要有唯一的名字，因为这个原因，在所有插件函数中使用唯一的函数名字前缀是个很好的主意。另一个可能性是在类中定义你的插件函数(也需要有唯一名字).
* 不要吧WordPress数据库表格前缀(通常是"wp_")放入你的插件中。确认使用不同的<tt>$wpdb->前缀</tt>来代替。 
* 数据库阅读很简单但是写确很难，数据库是非常善于取数据给你，而且这些操作(通常是)如闪电般迅速。在数据库中做改动，却是一个复杂的多的过程，很难。所以试着最小化<em>写入</em>的数量。首先在你的代码中准备好一切，这样你只需要选择那些你需要的写操作。
* 只选择你需要的。尽管数据库取数据非常快，你需要试着减少数据库的负载，通过只选择你需要的数据。如果你需要知道一个表格有多少行，不要<tt>SELECT * FROM</tt>，因为所有行中的所有数据都会被牵扯到，浪费内存。这样，如果你只需要插件中的post_id 和post_author，只要<tt>SELECT</tt>那些特定的区域，来减小数据库负载。记住: 大量的其他进程可能同时需要使用数据库。数据库和服务器每个都有大量的资源供这些进程使用。了解如何减小你的插件需要的资源会保证你的插件不会是被人说成滥用资源的哪种。


= External Resources =
* [http://amiworks.co.in/talk/simplified-ajax-for-wordpress-plugin-developers-using-jquery/ Simplified AJAX For WordPress Plugin Developers using Jquery](10APR08)
* [http://www.rafaeldohms.com.br/2008/03/10/desenvolvendo-plugins-para-wordpress/pt/ "Desenvolvendo Plugins para WordPress" by Rafael Dohms (in Brazilian Portuguese)] (10MAR08)
* [http://www.devlounge.net/extras/how-to-write-a-wordpress-plugin 12 part "How to Write a Wordpress Plugin" at DevLounge.net] by [http://ronalfy.com Ronald Huereca] ([http://www.devlounge.net/publik/Devlounge%20-%20How%20to%20Write%20a%20Wordpress%20Plugin.pdf PDF])
* [http://ditio.net/2007/08/09/how-to-create-wordpress-plugin-from-a-scratch/ How to create WordPress Plugin from a scratch] (9AUG07)
* [http://www.devlounge.net/articles/using-ajax-with-your-wordpress-plugin Using AJAX with your WordPress Plugin], also at DevLounce.net (25MAY07)
* [http://asymptomatic.net/2005/02/22/1328/how-to-write-a-simple-wordpress-plugin/ "How to Write a Simple WordPress Plugin" at asymptomatic.net] (22FEB05)

= 外部资源 =
* [http://amiworks.co.in/talk/simplified-ajax-for-wordpress-plugin-developers-using-jquery/ 为WordPress插件开发人员使用的Jquery的简单化AJAX](10APR08)
* [http://www.rafaeldohms.com.br/2008/03/10/desenvolvendo-plugins-para-wordpress/pt/ "Desenvolvendo Plugins para WordPress" by Rafael Dohms (巴西语和葡萄牙语)] (10MAR08)
* [http://www.devlounge.net/extras/how-to-write-a-wordpress-plugin 12 part "如何写Wordpress 插件" at DevLounge.net] ，来自 [http://ronalfy.com Ronald Huereca] ([http://www.devlounge.net/publik/Devlounge%20-%20How%20to%20Write%20a%20Wordpress%20Plugin.pdf PDF])
* [http://ditio.net/2007/08/09/how-to-create-wordpress-plugin-from-a-scratch/ 如何创建WordPress插件] (9AUG07)
* [http://www.devlounge.net/articles/using-ajax-with-your-wordpress-plugin在 your WordPress 插件中使用AJAX], DevLounce.net上也有 (25MAY07)
* [http://asymptomatic.net/2005/02/22/1328/how-to-write-a-simple-wordpress-plugin/ "如何写一个简单的WordPress插件" asymptomatic.net] (22FEB05)