🧩 插件开发指南
emlog支持插件机制,这样使得开发者可以方便地向系统中添加自己需要的功能。
实现原理
在emlog整个运行过程中我们设定了一些动作事件,遇到这些事件时emlog会自动的调用插件绑定到该事件的上的所有插件函数,从而实现插件的功能。
挂载点函数:doAction
doAction 函数内置于emlog核心代码中,就是所谓的插件挂载点。
//这是首页head头的挂载点,首页加载的时候会执行该挂载点上挂载的插件函数。
doAction('index_head')
插件挂载: addAction
addAction 用于插件向挂载点挂载自身函数,写在插件文件中。 有两个参数:挂载点名称 和 插件自身函数名称。
// 插件的 add_some_style 函数挂载到系统的 index_head 挂载点上,只要系统执行到 index_head 挂载点时,就会调用 add_some_style 函数.
addAction('index_head','add_some_style');
function add_some_style() {
// 添加一些样式等操作
}
开发规范
文件结构
- 插件目录:/content/plugins,插件目录下每一个文件夹即为一个插件
- 插件英文别名:如系统自带的小贴士插件英文别名为: tips,仅识别 插件英文别名/插件英文别名.php” 目录结构的插件,如: tips/tips.php
| 文件 | 说明 |
|---|---|
| xxx.php | 插件主文件 |
| xxx_callback.php | 事件回调相关函数文件 |
| xxx_setting.php | 插件后台设置页面(仅管理员可见) |
| xxx_user.php | 插件后台设置页面(所有人可见) |
| xxx_show.php | 插件前台页面 |
| preview.jpg | 插件图标,用于后台插件列表展示,尺寸:75x75 像素 |
上面表格中的 xxx 为插件英文别名,下面有插件文件的详细介绍。
插件主文件
插件文件夹下 插件名.php 的文件即为插件主要文件,例如:默认的tips插件,其文件夹名称为 tips, 插件主文件名称为 tips.php
tips.php 文件开头注释内容是插件的必要信息,该信息会显示在后台插件管理界面,务必完整填写。参考如下:
<?php
/*
Plugin Name: 小贴士
Version: 3.0
Plugin URL:https://www.emlog.net/plugin/detail/xxx
Description: 在后台首页展示一句使用小提示,也可作为插件开发的demo。
Author: emlog
Author URL: https://www.emlog.net
*/
其中 Plugin URL 和 Author URL 请使用官网 emlog.net 的应用链接和作者页,其他非官网链接不会在后台插件列表展示超链接。
事件回调
在emlog后台的插件管理页面,用户可以开启插件、关闭插件、删除插件,还可以更新插件。这些操作有的会触发对应的回调函数。 开发者可以给插件添加文件: pluginname_callback.php 来定义特定事件的回调函数,来实现插件初始化、插件数据清理、数据结构更新等操作。
| 事件 | 触发函数 |
|---|---|
| 开启插件 | callback_init() |
| 删除插件 | callback_rm() |
| 更新插件 | callback_up() |
示例:
tips_callback.php
<?php
!defined('EMLOG_ROOT') && exit('access denied!');
// 插件开启时调用,可用于初始化配置
function callback_init() {
$plugin_storage = Storage::getInstance('plugin_name');
$r = $plugin_storage->getValue('key');
if (empty($r)) {
$default_data = [
'ip' => [],
'time' => [],
'attempt' => [],
];
$plugin_storage->setValue('temp', json_encode($default_data), 'string');
}
}
// 插件删除时调用,可用于数据清理
function callback_rm() {
$plugin_storage = Storage::getInstance('plugin_name'); //使用插件的英文名称初始化一个存储实例
$ak = $plugin_storage->deleteAllName('YES'); //删除此插件创建的所有数据, 请传入大写的"YES"来确认删除。
}
// 插件更新时调用,可用于数据库变更等
function callback_up() {
...
}
☘️ 绿色插件
使用事件回调机制打造绿色插件,所谓绿色插件要做到:
- 插件启动和使用中不修改、添加、删除核心数据表字段
- 安装插件不需要额外添加插件自定义的挂载点,均采用官方预留的挂载点(个别主题缺少挂载点,可以引导用户添加官方挂载点)
- 插件删除时清理掉所有该插件的数据,包括自建的数据库表以及配置信息
插件后台设置页面(仅管理员可见)
如果你想让插件在后台有一个设置页面,可以:
- 在插件中添加文件: pluginname_setting.php
- 该文件内要包含名为 plugin_setting_view 的函数,其中可以输出设置内容 此时插件的后台配置地址为:https://yourdomain/admin/plugin.php?plugin=pluginname
- 插件设置界面可以直接基于 Bootstrap4 构建,请参考默认的小贴上插件
插件后台功能页面(所有用户均可见)
如果你想让插件在后台有一个功能页面,可以:
- 在插件中添加文件: pluginname_user.php
- 该文件内要包含名为 plugin_user_view 的函数,其中可以输出功能内容 此时插件的后台功能地址为:https://yourdomain/admin/plugin_user.php?plugin=pluginname
- 插件设置界面可以直接基于 Bootstrap4 构建,请参考默认的小贴上插件
该页面可以用来构建一些给普通注册用户使用的后台功能,比如文章收藏插件就使用了该特性。
插件前台页面
如果想让插件在前台输出一个页面,可以在插件中添加文件: pluginname_show.php 此时插件的前台显示地址为:https://yourdomain/?plugin=pluginname 或者 https://yourdomain/plugin/pluginname (需要开启伪静态规则) 这样就可以在 pluginname_show.php 文件中构建插件的前台展示页面了。
更多插件路由
要实现一些复杂的插件路由,有两种方式:
第一种:静态路由(需要开启伪静态),比如用于回调插件API的路由:https://yourdomain/plugin/pluginname/callback plugin/pluginname 和 plugin/pluginname/xxxx 都会路由到插件的 pluginname_show.php 文件,然后通过获取路径中的xxxx来判断具体要展示的内容。php示例如下:
<?php
// 从 URL 路径中获取 callback 部分
$path = $_SERVER['REQUEST_URI'];
$segments = explode('/', trim($path, '/'));
$action = isset($segments[2]) ? trim($segments[2]) : '';
if ($action === 'callback') {
// 处理回调逻辑
} else {
// 展示插件前台页面
}
第二种:动态路由(无需开启伪静态),比如用于展示插件文章列表的路由:https://yourdomain/plugin/pluginname?action=list
在 pluginname_show.php 文件中,通过获取 $_GET['action'] 来判断具体要展示的内容。php示例如下:
<?php
// 从 URL 路径中获取 action 部分
$action = Input::getStrVar('action');
if ($action === 'list') {
// 展示插件文章列表
} else {
// 展示插件前台页面
}
命名规则
插件英文别名
请以小写的英文字母、数字、下划线(_)、横杠(-) 组合而成,且只能以字母作为开头
如: tips、 em_ai
插件内自定义函数命名
函数采用 "插件英文别名_" 作为前缀来命名,如:tips_init,其中 tips 为插件英文别名。
function tips_init() {
global $array_tips;
$i = mt_rand(0, count($array_tips) - 1);
$tip = $array_tips[$i];
echo "<div id=\"tip\"> $tip</div>";
}
采用这样的命名方式可以避免与其他插件的函数出现冲突.
插件文件名称
- 插件文件命名推荐使用自定义前缀,避免和其他插件冲突,如: myprefix_tips ,其中 myprefix_ 为自定义前缀。
- 插件主文件名称必须与插件所在文件夹名称相同,如:
myprefix_tips/
myprefix_tips.php
myprefix_tips_setting.php
myprefix_tips_callback.php