WordPress插件开发入门

WordPress

类型：CMS系统

简介：一款开源的内容管理系统（CMS），用于构建和管理网站。

百科词条 访问网站

WordPress开发准则是不改变WordPress内核，简单理解就是不能通过改变WordPress核心文件来为网站添加功能。站长想要对其站点进行功能补充时一般需要使用WordPress提供的API，这时候就需要对插件或主题进行开发。本篇主要分享有关WordPress插件开发的基础支持，主题开发相关知识将在后续陆续分享。

一、WordPress插件介绍

WordPress插件是开源博客程序WordPress的功能扩展组件，是扩展WordPress核心功能的代码包，WordPress插件由PHP代码和其他相关资源（如图像、CSS和JavaScript）组成。而大多数WordPress插件都是由很多文件组成的，但是插件实际上只需要一个主文件，在这个文件中，有特定格式的DocBlock作为文件头，包含WordPress插件的一些信息，以便WordPress识别这个插件。

WordPress插件就是一个带有WordPress插件头注释的PHP文件，为了后续插件文件的方便维护，在开发WordPress插件之前建议创建一个目录。

二、WordPress插件开发基础介绍

创建新WordPress插件的具体步骤如下：

• 进入WordPress站点的wp-content/plugins目录；
• 新建一个以插件名称命名的目录（例如plugin-name）；
• 进入刚创建的目录；
• 新建一个PHP文件（建议文件名与目录名保持一致，也可自定义其他名称）。

在类Unix系统中可通过命令行完成上述操作，具体命令如下：

wordpress$ cd wp-content/plugins
plugins$ mkdir plugin-name
plugins$ cd plugin-name
plugin-name$ vi plugin-name.php

注：上述命令中的vi是文本编辑器的名称，可替换为自己常用的编辑器。

打开新建的PHP文件后，首先要为插件添加插件头注释，这是一段特殊格式的PHP块注释，包含插件名称、作者等元数据。头注释至少需包含插件名称这一项；若插件有多个PHP文件仅主文件需添加该头注释，其他文件无需包含。

最基础的插件头注释示例如下：

<?php
/*
Plugin Name: YOUR PLUGIN NAME
*/

保存文件后，登录WordPress后台并打开已安装插件列表即可看到刚创建的插件。

1、钩子：Action与Filter

WordPress钩子是无需修改核心文件就能介入WordPress代码执行流程、改变其运行行为的关键工具。WordPress钩子分为Action和Filter两类：

Action用于新增或修改 WordPress 的功能；Filter用于修改用户提交的内容或展示给用户的内容。

除了插件开发，钩子在WordPress核心功能中也被广泛应用。部分钩子本质是WordPress预留的占位符，方便开发者灵活扩展功能，这也是WordPress具备高灵活性的核心原因。

2、插件开发的基础钩子

开发插件时有3个基础钩子需重点掌握，分别对应插件的激活、禁用和卸载操作：

• register_activation_hook()：插件激活时触发，可用于执行初始化操作；
• register_deactivation_hook()：插件禁用时触发，可用于清理临时数据；
• register_uninstall_hook()：插件卸载时触发，可用于彻底清理插件相关数据。

3、添加自定义钩子

通过do_action()函数可自定义专属钩子。其他开发者可借助这些自定义钩子，对你的插件进行扩展或修改，以适配他们的需求。

4、移除钩子上的函数

使用remove_action()函数可移除挂载到某个钩子上的已定义函数。例如若A插件是B插件的扩展，可通过该函数移除B插件挂载到钩子上的回调函数，再替换为A插件的自定义回调函数。

不过需要注意，使用remove_action()时需关注插件Action的优先级，且该函数必须在初始的add_action()之后执行。

更多参考：《WordPress插件开发——钩子(Hooks)》

5、WordPress API

WordPress提供了丰富的应用程序接口（APIs），这些API能大幅减少插件开发的代码量，并且无需重复编写已验证的稳定功能，直接调用API即可实现需求。常用的API包括：

• 选项API
• HTTP API
• 插件API

6、WordPress插件的加载机制

当打开WordPress后台已安装插件列表时，WordPress会自动搜索wp-content/plugins目录及其子目录，寻找带有插件头文件的PHP文件。

若插件仅由一个PHP文件构成（如经典插件 “Hello Dolly”），可直接将文件放在wp-content/plugins根目录；更常见的做法是为插件创建专属目录，将所有插件文件放入该目录，并建议目录名与主文件名保持一致。

三、WordPress插件头文件要求

WordPress插件头文件是WordPress识别插件的关键，至少需包含插件名称，建议补充以下信息：

• 插件名称：（必需）你的插件名称，会显示在WordPress后台的插件列表中；
• 插件 URI：插件主页，应该是唯一的URL，最好在你自己的网站上。对于你的插件来说，必须是独一无二的，不能使用WordPress.org上的网址；
• 描述：插件的简短描述，在 WordPress插件管理界面显示，不要超过 140 个字符；
• 版本：插件的当前版本号，例如 1.0 或 1.0.3；
• 作者：插件作者名字，如果插件有多个作者，作者之间可以使用逗号分隔开；
• 作者URI：作者网站或其他网站上的个人资料，如WordPress.org；
• 许可证：插件许可证简称（slug）（例如GPL2）；
• 许可证URI：许可证的全文链接；
• 文本域：插件的 Gettext 文本域。更多信息可以在如何国际化您的插件页面的文本域部分找到；
• 域名路径：域名路径告诉 WordPress 在哪里可以找到翻译。更多信息可以在如何国际化您的插件 页面的域路径部分找到。

规范的插件头注释示例如下：

<?php
/*
Plugin Name: WordPress.org Plugin
Plugin URI: https://developer.wordpress.org/plugins/the-basics/
Description: Basic WordPress Plugin Header Comment
Version: 20160911
Author: WordPress.org
Author URI: https://developer.wordpress.org/
License: GPL2
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: wporg
Domain Path: /languages
*/

四、软件许可证

多数WordPress插件采用GPL许可证，也可选择其他许可证，但无论选择哪种，都建议在插件中明确标注。除了在头文件中注明许可证，另一种推荐做法是在插件主文件顶部添加许可证块注释，示例如下：

/*
{Plugin Name} 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
any later version.

{Plugin Name} 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 {Plugin Name}. If not, see {URI to Plugin License}.
*/

将许可证块注释与插件头注释结合后，完整格式如下：

<?php
/*
Plugin Name: WordPress.org Plugin
Plugin URI: https://developer.wordpress.org/plugins/the-basics/
Description: Basic WordPress Plugin Header Comment
Version: 20160911
Author: WordPress.org
Author URI: https://developer.wordpress.org/
Text Domain: wporg
Domain Path: /languages
License: GPL2

{Plugin Name} 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
any later version.

{Plugin Name} 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 {Plugin Name}. If not, see {License URI}.
*/

五、激活/禁用钩子

激活和禁用钩子可让插件在激活或禁用时自动执行特定操作，两者的适用场景有明确区别，需注意区分。

1、激活钩子

插件激活时触发，可用于执行初始化操作，例如：

register_activation_hook( __FILE__, 'pluginprefix_function_to_run' );

2、禁用钩子

插件禁用时触发，可用于清理临时数据，例如：

register_deactivation_hook( __FILE__, ‘pluginprefix_function_to_run’ );

3、参数说明与示例

上述两个函数的第一个参数，均需指向插件的主文件。通常这两个函数在主文件中调用，若需放在其他文件，需更新第一个参数的路径，确保指向正确。

激活钩子示例：刷新固定链接缓存

当插件注册自定义文章类型时，激活时需刷新 WordPress 固定链接缓存，避免访问自定义文章类型页面时出现 404 错误，示例代码如下：

function pluginprefix_setup_post_type() {
// 注册 book 自定义文章类型
register_post_type( 'book', ['public' => 'true'] );
}
add_action( 'init', 'pluginprefix_setup_post_type' );

function pluginprefix_install() {
// 触发注册自定义文章类型操作
pluginprefix_setup_post_type();

// 注册文章类型之后，刷新固定链接缓存
flush_rewrite_rules();
}
register_activation_hook( __FILE__, 'pluginprefix_install' );

禁用钩子示例：反注册文章类型

插件禁用时，可反注册自定义文章类型并再次刷新缓存，示例代码如下：

inprefix_deactivation() {
// 反注册文章类型
unregister_post_type( 'book' );
// 刷新固定链接缓存
flush_rewrite_rules();
}
register_deactivation_hook( __FILE__, 'pluginprefix_deactivation' );

六、WordPress插件卸载方法

方法 1：使用register_uninstall_hook()

register_uninstall_hook(__FILE__, 'pluginprefix_function_to_run');

方法 2：使用uninstall.php文件

在插件根目录（如/plugin-name/）创建uninstall.php文件；在文件开头添加常量检查，确保文件不被直接访问，示例代码如下：

/plugin-name/uninstall.php

注：使用 uninstall.php 时，在执行之前应先检查常量 WP_UNINSTALL_PLUGIN 以防止直接访问。此常量在 uninstall.php 调用期间由 WordPress 定义。由 register_uninstall_hook() 执行卸载时，常量不会被定义。