插件开发

插件是「一个目录 + 一份清单」,内核按清单注册前台页、后台页、侧栏块与数据表。当前内置 20 个插件,plugins/market、plugins/poly、plugins/site 都是完整范例。

本页导航

目录结构

plugins/<id>/
  plugin.php       # 清单(返回数组,必需)
  boot.php         # 启用时加载(注册钩子等)
  admin.php        # 后台页(admin_file / admin_fn)
  page.php         # 前台独立页(page_file / page_fn)
  migrations/      # 幂等迁移 *.sql 或 *.php
  assets/          # 静态资源

plugin.php 清单

字段说明
id / name / ver / desc / author / license基本信息,/plugin 直接读取
requires.core依赖内核版本
toggle是否允许停用
tables自有表名(安装/卸载据此建表与清理)
pages前台页 [['slug'=>'hello','title'=>'示例']] → 路由 /hello
blocks侧栏块 [['id'=>'hello','label'=>'示例块']]
register_file启用时 include 的文件(通常 boot.php)
admin_file / admin_fn后台页文件与渲染函数
page_file / page_fn前台页文件与函数,返回 ['html'=>…, 'title'=>…]
uninstall['tables'=>[], 'options'=>[], 'like'=>[]] 清理声明

最小插件

plugins/hello/plugin.php:

<?php
return [
  'id' => 'hello', 'name' => '示例插件', 'ver' => '0.1.0',
  'desc' => '最小插件示例', 'author' => 'YeCha', 'license' => 'MIT',
  'requires' => ['core' => '1.2.5'], 'toggle' => true,
  'pages' => [['slug' => 'hello', 'title' => '示例页']],
  'register_file' => 'boot.php',
  'page_file' => 'page.php', 'page_fn' => 'hello_page',
];

plugins/hello/page.php:

<?php
function hello_page(string $slug): array {
    return [
        'html'  => '<h1>Hello</h1><p>来自示例插件,服务端直出。</p>',
        'title' => '示例页 · ' . site_label(),
    ];
}

后台「插件」启用后访问 /hello 即生效。注意 slug 不能与 Router::RESERVED(login、admin、feed、category、tag、mall、site、ai 等)冲突。

前台路由与多级路径

  • 单段 /<slug> 命中 Plugins::pages() 后交给 page_fn;多级路径(如 /site/products)由 Router 收口为 kind=site|mall|ai,其余插件在 $GLOBALS['YC_PLUGIN_PATH'] 里拿到剩余段自行解析。
  • 三种业务前缀 mall / site / ai 在 core/Router.php 有专门分支;插件停用或未安装时对应分支回落 404。
  • 页面函数返回 html / title,必要时可返回 side、toc 等结构(参考 plugins/market/page.php)。
  • 内容页想用干净 URL(不带 .html),需在 Router 里加白名单(现有 docs、changelog 即此机制)。

后台页与权限

  • admin_fn 由后台 ?s=plug_<id> 分发,必须先验证管理员会话(Auth)。
  • 所有写操作表单带 Csrf::field(),处理端 Csrf::check();不要相信 $_POST 里的 id/表名。
  • 输出统一走 e();数据库访问用 Db 的预处理与 Db::t() 自动表前缀。
  • 后台菜单可用 Plugins::activeMenus() 追加,标签与说明来自清单。

数据表与迁移

  • 自有表统一用 Db::t('xxx') 加前缀(默认 ye_),并在清单 tables 里声明,卸载时才能被正确清理。
  • 迁移放 migrations/,用 CREATE TABLE IF NOT EXISTS、先查后加列等方式保证幂等;内核 Upgrade::apply() 记录执行历史(ye_migrations),重复执行无副作用。
  • CLI 预演 / 应用:
php tools/upgrade.php --component core --dry-run
php tools/upgrade.php --component core
  • 插件启用时会自动执行自己的迁移;迁移失败会在后台明确报错,不要吞异常。

Hooks 现状

core/Hooks.php 提供 Hooks::on($point, $fn, $prio) / Hooks::run($point, $payload),载荷为数组、按优先级顺序传递。

以源码为准:当前生产里真正被触发的点只有两个——

挂载点触发位置
front.shellindex.php 输出整页外壳前
admin.editor.tailadmin/posts.inc.php 编辑器尾部

route、front.xml 等注册点有插件在用,但内核并没有统一的 Hooks::run('route') 分发;商城/图片优化等模块都改为直接调用。因此:

  • 需要接管路由时优先用 pages 清单与 Router 分支,别依赖未触发的钩子;
  • 需要在页面外壳或编辑器尾部注入内容,才用上面两个真实挂载点;
  • 写插件前先 grep -rn "Hooks::run" . 确认当前内核的触发点,版本间可能变化。

停用与卸载

  • 停用:只停止注册,plugin.<id>.enabled=0,数据表与配置全部保留,可随时启用。
  • 卸载 purge=0:移出列表、停用,数据保留,重装后继续用。
  • 卸载 purge=1:按 uninstall.tables / options / like 删除自有表与配置;后台会先自动备份,确认无误再执行。
  • 卸载会自动清理 plugin.<id>.* 选项;共享表不要在 tables 里声明。

发布与校验

  • [ ] 逐文件 php -l;清单字段与实际文件一一对应
  • [ ] 迁移幂等:连续执行两次结果一致,--dry-run 无意外项
  • [ ] 前台页、后台页、侧栏块都做过启用/停用/卸载回归
  • [ ] 包内不含密钥、var/cache、上传目录、备份文件
  • [ ] 云市场安装只接受 https + SHA-256 校验;先在本地装一遍再上传
  • [ ] 改动涉及内核时按 RELEASE.md 走发版流程