插件是「一个目录 + 一份清单」,内核按清单注册前台页、后台页、侧栏块与数据表。当前内置 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.shell | index.php 输出整页外壳前 |
admin.editor.tail | admin/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里声明。