开发文档 ›全部章节 ›入门 ›插件包

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。