2. 插件包
一个插件就是主程序 public/ 下的一个文件夹。扫描只认 plugin.json;
主类继承 DTR\Core\Plugin,靠钩子和路由把自己挂进站点,不改核心一行代码。
2.1 目录结构
public/你的目录名/
├─ plugin.json 插件信息。后台「插件管理」只认这个文件
├─ 你的目录名.php 入口文件,里面是插件主类
├─ config.json 开关与设置,由框架读写;新装时框架强制 enabled=0
├─ .htaccess 挡掉包里的 php/json/txt/html 直链,没有的话框架自动补
├─ views/page.php 插件自带的前台页面
├─ public/ 插件自己的 css / js / img,用 asset() 取地址
└─ data/ 插件自己的数据文件,升级时框架原样保留
2.2 plugin.json 每个键
{
"name": "mytool",
"title": "我的小工具",
"version": "1.0.0",
"author": "张三",
"desc": "一句话说明这个插件干什么。",
"entry": "mytool.php",
"class": "DTR\\Plugins\\Mytool",
"has_config": 1,
"has_admin": 0,
"tables": ["mytool_log", "mytool_data"],
"deps": {"pay": "支付中心"},
"deps_rec": {"cron": "定时任务中心"}
}
| 键 | 必填 | 干什么 | 校验与注意 |
|---|---|---|---|
name | 是 | 插件目录名 | 只能是字母数字下划线短横线,1 到 40 位;必须等于官网标识 ID 里那段 |
title | 是 | 后台与商店显示的中文名 | |
version | 是 | 版本号 x.y.z | |
author | 是 | 作者 | |
desc | 是 | 一句话说明 | |
entry | 否 | 入口文件名 | 不写就按 <name>.php 找;写了就必须指向包里真实存在的 .php,否则拒装 |
class | 是 | 入口文件里的完整类名 | 留空直接拒装。形如 DTR\Plugins\Mytool,必须和入口文件里的 class 一字不差。后台脚手架按 name 分段首字母大写替你填这个类名:my-tool 出 MyTool,mytool 出 Mytool;运行时框架只读这一行,不猜类名 |
has_config | 否 | 非空就短路:后台列表直接出「设置」按钮 | 写 0 或不写不等于关掉,那时框架再看 adminForm() 返不返回内容,返回了照样有按钮 |
has_admin | 否 | 给审核和商店看的一个标记 | 框架目前不读它,有没有自己的后台页要看代码 |
tables | 否 | 这个插件自己建的数据表名 | 不写 dtr_ 前缀;表名必须以插件目录名开头,否则被忽略 |
deps | 否 | 必需依赖 | 形如 {"pay":"支付中心"};没满足就开不起来 |
deps_rec | 否 | 推荐依赖 | 缺了照样能开,只在后台提示 |
JSON 里不能写注释,反斜杠要写成两条:"class": "DTR\\Plugins\\Mytool"。
2.3 入口写法
<?php
namespace DTR\Plugins;
use DTR\Core\Plugin;
use DTR\Core\Hooks;
class Mytool extends Plugin
{
/** 必须实现:挂钩子。插件开启时框架才调这儿 */
public function register(): void
{
Hooks::listen('front_footer_extra', function () {
if (!$this->config('enabled', 0)) {
return;
}
echo '<a href="' . site_url('/mytool.html') . '">我的工具</a>';
});
}
/** 前台路由:正则 => 回调,正则匹配的是不含域名和子目录的路径 */
public function routes(): array
{
return [
['@^/mytool\.html$@', function () { $this->renderFront('page'); }],
];
}
/** 数据表:第一次用到时惰性建,别在安装脚本里建 */
public static function ensureTables(): void
{
$db = \DTR\Core\App::db();
$db->exec('CREATE TABLE IF NOT EXISTS {{mytool_log}} (
`id` int(11) NOT NULL AUTO_INCREMENT,
`created_at` datetime NOT NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci');
}
}
register() 是唯一必须实现的方法,插件开启时框架才调它;关闭状态下钩子和路由都不生效。
2.4 钩子与挂载点
钩子在 DTR\Core\Hooks:listen(钩子名, 回调, 优先级) 挂,
模板或控制器用 fire() 触发不取返回值、filter() 触发并把值传回来改。
优先级小的先跑,默认 10。
// 依赖没满足时,框架在「开启」这一步就拦下来,提示原文如下
// deps 里的没开启:
开启前先开启它依赖的插件:「支付中心」。
// deps 里的根本没装:
本插件依赖的「支付中心」(pay) 还没安装,请到「插件管理 → 导入插件包」上传该插件的 zip 再开启。
// deps_rec 里的缺了不拦,只在后台给一句提示,功能少一块照样能开
模板里没有留钩子的位置你就挂不进去。上面 第 13 节 是全量钩子清单, 写模板时按 default 那套把钩子留全,做插件时照着清单挑。
2.5 前台路由与页面
routes() 返回 [正则, 回调] 的数组,正则匹配的是不含域名与子目录的路径,命中就交给你的闭包。
页面用 renderFront('page') 渲染插件自己 views/ 下的文件,
并自动套客户当前启用模板的头尾,风格跟着模板走。框架会给你注入 $plugin、$page、$seo_title。
写法见 2.3 那个入口类:routes() 返回 [正则, 回调],回调里调 renderFront()。
正则里的路径不含域名也不含子目录,站点装在 /dtr/ 下也照样只写 ^/mytool\.html$;
renderFront() 传的是不带 .php 的文件名,只允许一层,出现斜杠会被剥掉。
2.6 后台设置与管理页
<?php namespace DTR\Plugins;
use DTR\Core\Plugin;
class Mytool extends Plugin
{
public function register(): void {}
/** 后台「设置」弹窗里的 HTML;返回 null 就没有设置 */
public function adminForm(): ?string
{
return '<label><input type="checkbox" name="enabled" value="1" '
. ($this->config('enabled', 0) ? 'checked' : '') . '> 开启插件</label>'
. '<label>每天最多几条 <input type="number" name="day_limit" value="'
. (int) $this->config('day_limit', 10) . '"></label>';
}
/** 后台点保存时调:自己把值写回 config.json */
public function adminSave(array $post): void
{
$this->saveConfig([
'enabled' => !empty($post['enabled']) ? 1 : 0, // 开关走框架,绕不过依赖检查
'day_limit' => max(1, (int) ($post['day_limit'] ?? 10)),
]);
}
/** 后台整页:/admin/plugin/run/mytool/xxx 会进来,直接 echo HTML 片段 */
public function adminAction(string $action): void
{
echo '<div class="page"><div class="panel">这里是插件自己的后台页。</div></div>';
}
/** 后台 AJAX:/admin/plugin/api/mytool/xxx,只出 JSON;POST 的 CSRF 框架已经查过 */
public function adminApi(string $action): void
{
json_out(['msg' => '好了', 'data' => []], 1);
}
}
- 设置弹窗
adminForm()返回一段 HTML,框架塞进弹窗;保存时adminSave($post)收到全部字段,自己saveConfig()写回 config.json。 开关enabled一定走saveConfig(),框架要在这一道做依赖检查。 - 整页管理地址是
/admin/plugin/run/插件名/动作,你在adminAction()里直接 echo HTML 片段。 框架会给它套后台外壳,所以你要用后台那套 class:外层div.page、卡片div.panel, 表格用table并让容器能横向滚动。别写固定宽度,后台是多标签页、面板宽度会变。 - AJAX 接口地址是
/admin/plugin/api/插件名/动作,不套外壳,自己json_out(); POST 的 CSRF 框架已经查过,你不用再查一遍。 - 加 css/js挂
admin_head钩子,按$args['where']判断是框架页还是片段页,资源地址用$this->asset('css/style.css')。 - 开启是前提插件没开启时,框架直接拦住这三样,提示原话是: 「插件【名字】还没开启,开启后才能设置。」「还没开启,开启后才能使用它的管理页。」接口则回 「插件未开启或接口不存在」。所以别在没开启的状态下偷偷读写数据。
- 定时任务
cronTask()报名给定时任务中心。
/** 向「定时任务中心」报名,后台能看到、能手动跑一次 */
public function cronTask(): ?array
{
return [
'title' => '清理过期记录',
'desc' => '每小时删一次三天前的临时数据',
'every' => 3600,
'run' => function () {
// 不能 echo、不能 exit,只把结果 return 回去
$n = \DTR\Core\App::db()->exec('DELETE FROM {{mytool_log}} WHERE created_at < ?', [date('Y-m-d H:i:s', time() - 259200)]);
return ['ok' => 1, 'msg' => '清掉 ' . (int) $n . ' 条'];
},
];
}
静态资源用 $this->asset(),它给的是 /public/目录名/public/相对路径;
插件目录里的 php、json、txt 这些由包自带的 .htaccess 挡住直链,你不用另外配。
2.7 依赖声明与拦截
两种依赖,行为不一样:
| 写法 | 含义 | 缺了会怎样 |
|---|---|---|
deps | 必需 | 开不起来,点开启直接给一句原因,前台页面也会显示占位提示 |
deps_rec | 推荐 | 照样能开,只在后台列表提示一句,对应功能少一块 |
两种写法都收:["pay"] 或 {"pay":"支付中心"}。后面这种能给没装的依赖显示中文名,建议用这种。
自己不能算进自己的依赖,重复的会自动去掉。
2.8 建表与卸载清理
- 表名规则
plugin.json的tables里 不写dtr_前缀,只写自己的名字。 表名只能是字母数字下划线、40 位以内,而且必须以插件目录名开头,比如toppay_slot;不满足这两条的名字框架直接忽略,卸载时也就不归它管。 - SQL 里用花括号建表语句写
{{mytool_log}},框架会换成dtr_mytool_log,Database::table()只做这一件事,别自己拼前缀。 - 什么时候建惰性建:类常量写好 SQL,用到时
CREATE TABLE IF NOT EXISTS。 装包、开启、升级都不替你建表,这样老客户换包不会因为建表失败中断。 - 两条安装路径不一样后台「导入模板包 / 导入插件包」是本地导入,同名目录已存在会拒绝, 提示「同名模板已存在:xxx,请先删除旧目录或修改包内的目录名」;从官网商店点安装是覆盖安装, 会先把旧目录改名备份再写入新包。
- 卸载后台删插件默认只删目录,数据表留着,免得误删客户数据;
卡片上勾了「删数据表」才按
tables里那份校验过的表名逐张DROP TABLE。 config.json 和 data 目录跟着目录一起走。 - 升级用包覆盖安装时,框架会把旧目录的
config.json和data/搬进新包, 你不用在插件里写迁移,但也别假设 config.json 里一定有某个键,读的时候给默认值。 - 新装状态新装的插件框架强制
enabled = 0,你config.json里写 1 也会被改掉, 必须让站长点开启。
内容有问题去论坛发帖,或直接联系老李 QQ 260468289。