插件与主题开发手册
EnovelCms开发者入门必看
写给要给 EnovelCms 写插件、写主题的人。公共函数、数据层、缓存、日志、邮件、设备判断、二维码、安全、语言包、视图、路由、后台界面、支付、定时任务,逐项给出方法签名、真实语义和可以直接复制运行的案例。读完你能独立做出一个能装、能配、能卸的插件,或一套能上线的主题。
全篇只描述框架现在真实提供的能力,不写设想中的 API。所有案例都是同一套写法:PHP 8.0 起可直接运行,不依赖 Composer、PECL 扩展或 Redis 这类可选服务。
开始之前
这套框架是原生 PHP 的 MVC,没有 Composer 自动加载、没有容器、没有事件总线框架。所有扩展能力都收敛在 app/core 下的几个静态类里,插件与主题通过"清单文件 + 入口文件 + 嵌入点"接入。理解这一点,后面所有 API 的形状就都顺了。
适用对象
- 要做一个独立功能插件(采集、支付、过滤、拦截、友情链接等),不改动核心代码。
- 要做一套前台主题(PC 固定宽或移动端),复用框架的数据与模板标签。
- 要给已有插件补后台设置页、列表列、编辑表单字段。
框架边界
- 只使用框架已有的类与函数。不引入新的第三方依赖,不假设服务器装了 Redis、Memcached、Composer。
- 不改
config/config.php里的常量名与数据库结构,插件自己的表自成体系。 - 插件与主题代码不写进
app/,不修改框架文件;框架确实缺能力时,补到app/core并按第 24 章的红线执行,不要在自己的插件里绕一套私有实现。
运行环境
| 项目 | 要求 | 说明 |
|---|---|---|
| PHP | 8.0 – 8.4 | 案例不使用 8.1+ 独有语法,8.0 起即可运行 |
| 扩展 | simplexml、gd、pdo_mysql、zip、mbstring | 清单解析用 simplexml,验证码与二维码用 gd,升级与导入用 zip |
| 数据库 | MySQL 5.7+ / MariaDB 10.3+ | 字符集 utf8mb4,引擎 InnoDB |
| 模板 | Smarty 5(vendor 内置) | 主题模板用 .tpl,不要用原生 PHP 混写 |
| 缓存 | 依赖后台设置,缺省自动退化为文件缓存 | CLI 下 所选缓存方式未加载时会自动降级,不需要额外配置 |
常量与上下文
| 常量 / 变量 | 何时存在 | 含义 |
|---|---|---|
ROOT_PATH | 始终 | 站点根目录,带结尾斜杠 |
PRIVATE_PATH | 始终 | 私有数据目录(站点内 data/),带结尾斜杠 |
BASE_URL / ADMIN_URL | 始终 | 前台与后台根地址;在 CLI 脚本里运行时需自行定义 |
DB_PREFIX | 始终 | 表前缀,由 config/config.php 的 DB_PREFIX 决定;后文为方便叙述统一写 En_ |
PLUGIN_BOOT | 插件 main.php 被 require 期间 | 插件入口的守卫常量,未定义时应直接 exit |
PLUGIN_PAGE_ACCESS | 前台插件页被 require 期间 | 前台插件页守卫;后台页守卫是 ADMIN_BOOT |
$id / $kind / $info / $db / $path / $url / $extension | 入口文件被 require 期间 | Extension::context() 解出的局部变量,插件入口可直接用 |
两个容易踩的坑。
一、后台物理目录是 admin,对外 URL 可能被代理映射成别的形状(/wensha/?action=xxx、/manage/?action=xxx 都见过)。代码里不要写死任何具体后台路径,统一用 ADMIN_URL 或 admin_url()。
二、直接 foreach $_GET / $_POST 取值会绕过过滤层,统一用 g() / p() / inp(),它们带类型转换与 token 清洗。
术语
| 术语 | 含义 |
|---|---|
| 扩展单元 | 一个插件或一套主题,有唯一 id(插件 ^[a-z][a-z0-9_]{2,30}$,主题 ^[a-z0-9_]+$) |
| 清单 | plugin.xml / theme.xml,声明元信息与依赖 |
| 入口文件 | 插件 main.php、主题 include.php,被框架 require 一次 |
| 嵌入点(hook) | 框架在执行过程中主动抛出的命名节点,分动作与过滤器两类 |
| owner | 注册嵌入点时的归属标记,形如 plugin:pc_gate;缺省自动取当前加载的扩展 |
| 信号 | 回调返回值 Hook::SIGNAL_STOP / SIGNAL_BREAK,用来提前结束链路 |
怎么用这份手册
章节顺序就是上手顺序:02 定目录与清单,07 理解扩展内核,05 / 06 学钩子与过滤器,08 / 09 分别进插件与主题,10 之后按需查。不必从头读到尾——先读完 02 与 07,你就能写出第一个能被后台识别的插件,其余章节当字典用。
| 你要做的事 | 直接跳到 |
|---|---|
| 建一个能被后台识别的插件 | 02 目录与必须文件 → 03 清单字段 → 08 插件 API |
| 在页面某处插入自己的输出 | 05 钩子(动作),章末有完整嵌入点总表 |
| 改写框架已有的输出(标题、分页、菜单) | 06 过滤器 |
| 给自己的插件建表、读写数据 | 10 数据层 |
| 加一个前台地址或接口 | 19 路由与页面入口 |
| 加后台设置页、列表列、编辑字段 | 20 后台界面扩展 |
| 上线前逐条核对 | 24 开发红线 → 25 上线检查与排错 |
每章结构统一:先给签名与真实语义,再给一段可复制运行的案例,最后列这一块特有的坑。案例里的路径、表名、插件 id 换成你自己的即可,不要直接沿用示例里的 id。
目录结构与必须文件
插件放 plugins/{id}/,主题放 templates/{id}/。目录名就是扩展 id,重命名目录等于换 id,数据库里的启用记录、配置键会全部对不上。所以先定 id,再建目录。
插件目录
plugins/pc_gate/ ├── plugin.xml ← 必须:清单 ├── main.php ← 必须:入口,注册钩子与类 ├── admin.php ← 可选:后台首页(?action=plugin&pid=pc_gate) ├── pages/ ← 可选:独立页面 │ ├── crawl.php ← 前后台共用目录,用守卫常量区分 │ └── apply.php ├── views/ ← 可选:Smarty 模板(Plugin::view 用) │ └── stats.tpl ├── lang/ ← 可选:语言包 │ ├── zh-cn.php │ └── en-us.php ├── assets/ ← 可选:静态资源,经 Plugin::url() 取地址 │ ├── css/pc_gate.css │ └── js/pc_gate.js ├── lib/ ← 可选:内部类库,main.php 里自行 require ├── controllers/ ← 可选:自定义控制器(需继承 Controller) └── cli/ ← 可选:命令行脚本,供 Cron 调用
主题目录
templates/default/ ├── theme.xml ← 必须:清单 ├── include.php ← 必须:入口,注册钩子 + theme_init() ├── config.php ← 可选:后台主题设置字段定义(返回数组) ├── views/ ← 必须(否则没有页面可渲染) │ ├── index.tpl │ ├── novel/detail.tpl │ └── ... ├── css/ js/ images/ ← 可选:主题资源 ├── lang/ ← 可选:主题语言包 └── screenshot.png ← 可选:后台主题卡片缩略图
必须文件与职责
| 文件 | 必须 | 职责 | 缺失后果 |
|---|---|---|---|
plugin.xml / theme.xml | 必须 | 元信息、依赖、能力声明 | 扫描不到,后台不显示该扩展 |
main.php / include.php | 必须 | 注册钩子、定义类与生命周期函数 | 扩展被"空载":启用成功但什么都不做 |
admin.php | 可选 | 插件后台首页(整页) | 后台退回自动配置页(若有 PluginConfig 字段) |
pages/*.php | 可选 | 独立页面:前台 /plugin/{id}/{page}、后台 ?action=plugin_page&pid={id}&page={page} | 对应 URL 404 |
config.php | 可选 | 主题设置字段定义 | 后台无"主题设置"页 |
views/*.tpl | 主题必须 | 页面模板 | 前台 500 或空白 |
命名规范
- 插件 id:
^[a-z][a-z0-9_]{2,30}$,小写字母开头,可含数字与下划线,3–31 字符。校验函数Security::validPluginId()。 - 主题 id:
^[a-z0-9_]+$,校验函数Theme::validThemeId()。 - 插件自建表:框架会自动加
{pluginId}_前缀,所以表名写items,真实表是En_pc_gate_items。不要自己再拼一次插件 id。 - 类名:插件类加前缀避免撞名(
PcGate、FriendLink);全局命名空间是扁平的,Stats这种名字一定会撞。 - 函数名:生命周期函数必须
plugin_install_{id}/plugin_uninstall_{id}/plugin_init_{id};主题用theme_init/theme_install_{id}/theme_uninstall_{id}/theme_upgrade_{id}。 - 生命周期只用函数,不建
install.php/uninstall.php/upgrade.php这类独立文件。插件与主题同一套机制,逻辑都写进main.php/include.php。
插件不要往 data/ 里自己写文件。
需要持久化就用自己的表(Plugin::createTable)或配置(Plugin::setConfig);需要缓存走 Cache 或 Extension::cacheSet;需要写日志走 Logger::plugin('{id}'),框架会落到 data/logs/plugins/{id}/。落盘路径、文件名与轮转由框架决定,插件不参与。
清单文件
清单是扩展对框架的"自我介绍",也是后台判断能否安装的唯一依据。解析走 simplexml,字段名大小写敏感,写错名字不会报错,只会静默按默认值处理——默认版本 1.0.0、默认 PHP 要求 8.0.0,看起来"能用",实际你的依赖声明全部失效。
plugin.xml
| 节点 | 必填 | 类型 / 取值 | 作用 |
|---|---|---|---|
<name> | 是 | 文本 | 后台显示名 |
<description> | 是 | 文本 | 后台简介,一行写完 |
<version> | 是 | 1.0.0 | 与注册表比对,新版本触发 plugin_upgrade_{id} |
<category> | 否 | security / crawler / payment / content / tool | 后台分类筛选 |
<cms_adapted> | 否 | 3.0 | 适配的程序版本线 |
<author> | 否 | 文本,或含 <name> 子节点 | 作者名 |
<author_url> | 否 | URL | 作者主页 |
<require><php> | 否 | 8.0,8.1,8.2,8.3,8.4 | 允许的 PHP 版本列表;校验时取第一项作下限 |
<require><plugins> | 否 | epay, epay_mapi>=1.0.0 | 依赖的插件,裸 id 视为插件 |
<advanced><dependency> | 否 | plugin:epay>=1.0.0 theme:default | 依赖(插件/主题混写) |
<advanced><conflict> | 否 | plugin:pc_gate | 冲突项,对方启用中则拒绝安装 |
<advanced><exists_functions> | 否 | qr_code_png, brand_title | 必须存在的框架函数,缺失即安装失败 |
<advanced><rewrite_functions> | 否 | 函数名列表 | 准备重写的框架函数,缺失只给警告 |
<sidebars> | 否 | 1-9 或 1,3,5 | 插件占用的侧栏槽位,供主题渲染 |
<?xml version="1.0" encoding="UTF-8"?>
<plugin>
<name>PC 访问拦截</name>
<description>电脑端访问前台自动拦截,可配状态码 404/403/410/451/500 与提示页;手机与平板放行并用前端屏幕宽度补判</description>
<version>1.0.0</version>
<cms_adapted>3.0</cms_adapted>
<category>security</category>
<author>EnovelCms</author>
<author_url>https://example.com/</author_url>
<require>
<php>8.0,8.1,8.2,8.3,8.4</php>
</require>
<advanced>
<exists_functions>qr_code_data_uri, is_mobile</exists_functions>
<conflict>plugin:friendlink</conflict>
</advanced>
<sidebars>1</sidebars>
</plugin>
插件清单里写 <settings>、<menus>、<config>、<screenshot> 都不会被解析——这几个节点只有主题清单支持。插件要配置项,用 PluginConfig::add() 在入口文件里声明(第 08 / 20 章)。
theme.xml
| 节点 | 必填 | 取值 | 作用 |
|---|---|---|---|
<id> | 是 | default | 必须与目录名一致,否则后台认不出 |
<name> | 是 | 文本 | 后台主题名 |
<type> | 是 | pc / mobile / both | 主题能设到哪一端。both 是响应式,PC 与手机都能设;只填一个值 |
<version> | 是 | 1.0.0 | 升版触发 theme_upgrade_{id} |
<author> / <website> | 否 | 文本 / URL | 作者与主页 |
<description> | 否 | 文本 | 后台简介 |
<level> | 否 | official / free / paid | 应用中心分级 |
<adapted> / <price> | 否 | 3.0.0 / 0 | 适配版本与价格 |
<screenshot> | 否 | screenshot.png | 缩略图;缺失时自动找 preview.png / cover.jpg |
<compatible_versions> | 否 | 3.0.0,3.0.1 | 兼容的程序版本 |
<requires><php> / <cms> | 否 | 8.0.0 / 3.0.0 | 最低版本要求 |
<sidebars> | 否 | 1-9 | 主题提供的侧栏槽位 |
<config> | 否 | config.php | 设置字段定义文件 |
<settings> | 否 | 子节点带 label/type/default 属性 | 清单直接声明设置项,免写 config.php |
<menus> | 否 | 子节点带 action/icon/group 属性 | 清单直接声明后台菜单 |
<type> 只认三个值,且只能写一个:pc 只能设为 PC 主题,mobile 只能设为手机主题,both 两端都能设(后台标签显示 PC + 手机)。写 pc,mobile 这种多值不合法,会被当成 pc;写成 responsive 会被归一到 both。启用时框架会拿清单类型和目标端比对,类型不符直接拒绝,不会把 PC 主题硬挂到手机端。
<?xml version="1.0" encoding="UTF-8"?>
<theme>
<id>default</id>
<name>EnovelCMS 默认主题</name>
<author>文煞</author>
<website>https://example.com/</website>
<version>1.0.0</version>
<description>默认主题,PC 端固定布局(设计宽度 1280px),移动端主题见 defaultm。</description>
<type>pc</type>
<level>official</level>
<adapted>3.0.0</adapted>
<price>0</price>
<screenshot>screenshot.png</screenshot>
<compatible_versions>3.0.0,3.0.1</compatible_versions>
<requires>
<php>8.0.0</php>
<cms>3.0.0</cms>
</requires>
<advanced>
<dependency></dependency>
<conflict></conflict>
<rewrite_functions></rewrite_functions>
<exists_functions></exists_functions>
</advanced>
<sidebars>1-9</sidebars>
<config>config.php</config>
</theme>
清单内联设置项(省掉 config.php 的写法)
<settings>
<reads_per_page label="每页显示条数" type="number" default="12"/>
<show_rank label="显示排行榜" type="switch" default="1"/>
<layout label="列表布局" type="select" default="grid"/>
</settings>
<menus>
<item action="theme_config" icon="fa-palette" group="appearance">主题设置</item>
</menus>
这两段等价于在 include.php 里调用 Extension::setting() 与 Extension::menu(),区别是清单声明不需要代码加载就能在后台列出,适合"纯展示型参数"。需要动态默认值或依赖数据库时,仍然写代码。
依赖与冲突声明语法
<advanced>
<dependency>plugin:epay>=1.0.0, plugin:word_filter, theme:default</dependency>
<conflict>plugin:pc_gate</conflict>
<exists_functions>qr_code_png, Security::safeUrl</exists_functions>
<rewrite_functions>brand_title</rewrite_functions>
</advanced>
分隔符是逗号或空格;每一项写 kind:id,省略 kind: 时按插件处理;>=版本 只做下限比较。校验结果由 Extension::checkRequirements() 返回三段结构:
array(
'ok' => false,
'errors' => array('依赖 plugin:epay 未安装,请先安装'),
'warnings' => array('依赖 plugin:word_filter 已安装但未启用'),
)
errors 非空即拒绝安装;warnings 只提示,不阻断。清单改动后务必 Extension::flushInfo('plugin', 'pc_gate') 清掉缓存,否则后台读到的还是旧版本号。
生命周期与加载时序
框架每个请求都走同一条启动流水线。插件与主题能做什么、不能做什么,取决于它在这条流水线上的站位:注册钩子要早,输出内容要晚,改路由要在路由之前。
Bootstrap 启动顺序
- defineConstants定义 ROOT_PATH、PRIVATE_PATH、BASE_URL、ADMIN_URL、DB_PREFIX、DEBUG 相关常量。
- functions.php载入全局函数,此后
g()、t_admin()、url()、qr_code_png()等随时可用。 - ErrorHandler / session / Cache::init注册异常与错误处理、开 session、按配置初始化缓存驱动(yac 不可用则退化成文件缓存)。
- Database + Model::setDb建立 PDO 连接(异常模式、关闭模拟预处理),并注入到 Model / 各扩展内核。
- SecurityGuard + 安全响应头UA 黑名单、IP 拦截、限流、恶意路径拦截;命中即直接输出拦截页并结束。
- View::init + Language::init + Ui::registerFront确定当前主题、装配模板目录、载入语言包、注册前台资源钩子。
- Theme::loadInclude按
active_theme与mobile_theme依次 require 主题include.php,在Extension::begin('theme', id)上下文中执行。 - Plugin::init按注册表顺序 require 已启用插件的
main.php,逐个Extension::begin/end,加载后注册插件语言包。 - Theme::init + Request + Router触发
core_before_controller,反射实例化控制器并执行方法,最后core_after_controller。
主题比插件先加载。同一优先级下,钩子按注册顺序执行,所以主题在 include.php 里注册的 output_filter 会先于插件执行;插件如果要"最后改写输出",把优先级设大(如 20),而不是靠加载顺序。
三个关键时机
| 时机 | 能做什么 | 不能做什么 |
|---|---|---|
| 入口文件被 require 时 | 定义类与函数、Hook::addAction/addFilter、PluginConfig::add、Extension::menu/setting/sidebar、PluginTable/PluginForm 声明 | 直接输出内容(此时响应头可能已发)、直接读 $_GET 决定业务(应放到钩子或页面里) |
| 前台插件页被 require 时 | 输出完整 HTML、读 $request、查库、用 $this 访问控制器 | 依赖主题布局自动包裹(框架不套模板,页面自己输出整页) |
| 后台插件页 / admin.php 被 require 时 | 使用后台样式与 ADMIN_BOOT 上下文、输出表单、调 PluginConfig::save | 在未验证 CSRF 的情况下处理写操作 |
插件入口的最小骨架
<?php
if (!defined('PLUGIN_BOOT')) exit;
class DemoPlugin
{
const PID = 'demo';
public static function boot(): void
{
PluginConfig::add(array(
'name' => 'notice',
'label' => '页脚提示文案',
'type' => 'text',
'default' => '',
));
}
}
function plugin_install_demo($db): void
{
Plugin::createTable('logs', array(
'id' => 'INT(11) NOT NULL AUTO_INCREMENT',
'message' => 'VARCHAR(255) NOT NULL DEFAULT ""',
'created' => 'DATETIME DEFAULT CURRENT_TIMESTAMP',
'__PRIMARY__' => 'id',
));
Plugin::setConfig('notice', '本站使用 CDN 加速', 'demo');
}
function plugin_uninstall_demo($db): void
{
Plugin::dropTable('logs');
$db->delete('plugin_data', array('plugin_id' => 'demo'));
}
function plugin_init_demo($db): void
{
DemoPlugin::boot();
Hook::addAction('body_end', function () {
$text = (string)Plugin::config('notice', '', 'demo');
if ($text !== '') {
echo '<div class="footer-notice">' . Security::h($text) . '</div>';
}
}, 12, 'plugin:demo');
}
三个生命周期函数的触发点:plugin_install_{id} 在后台点"安装"时执行一次;plugin_uninstall_{id} 在卸载时执行;plugin_init_{id} 每次请求加载插件时执行,是注册钩子的标准位置。文件末尾直接写 Hook::addAction 也可以,但用 plugin_init_{id} 包装后语义更清楚,也便于单独调试。
钩子(动作)
全站一共 84 处触发点、74 个名称,逐个的参数与位置列在 27 章嵌入点总表;这一章只讲语义与纪律。
动作是"告知型"嵌入点:框架在某个时刻喊一声,谁注册了就执行谁,执行完继续走自己的流程。它不回传值,也不改变框架的行为——除非回调里显式返回信号或直接终结请求。
Hook::addAction(string $hook, callable $callback, int $priority = 10, ?string $owner = null): void
Hook::doAction(string $hook, ...$args): bool
执行顺序
- 先按
$priority升序(数值越小越早),同一优先级内按注册顺序(先注册先执行)。 $owner被Hook::suspendOwner()挂起时,该 owner 的回调整条跳过,但注册关系保留,resumeOwner()后立即恢复。- 回调抛异常会被捕获并写
error_log,链路继续——一个插件出错不会拖垮整站,但也意味着"没生效"不会有人告诉你,调试时要看日志。 doAction返回 bool:正常走完返回true,被SIGNAL_STOP中断返回false。
信号语义
| 回调返回 | 动作(doAction) | 过滤器(applyFilters) |
|---|---|---|
无返回 / null | 继续下一个回调 | 值不变,继续下一个(返回 null 不会把值改成 null) |
| 任意普通值 | 忽略 | 覆盖当前值,作为下一个回调的输入 |
Hook::SIGNAL_BREAK | 跳过当前优先级剩余回调,继续下一优先级 | 同左 |
Hook::SIGNAL_STOP | 整条链路立即终止,doAction 返回 false | 整条链路终止,返回此刻已累积的值 |
SIGNAL_BREAK 不是"全部终止"。
它只跳出同一优先级的后续回调;下一优先级的回调照样执行。想彻底截断链路用 SIGNAL_STOP。这两个信号值都是字符串(__hook_stop__ / __hook_break__),比对是严格相等,返回同字面量的字符串也算命中。
案例:注册、优先级、清理
<?php
if (!defined('PLUGIN_BOOT')) exit;
Hook::addAction('head_end', function () {
echo '<meta name="x-demo" content="early">';
}, 5, 'plugin:demo');
Hook::addAction('head_end', function () {
echo '<meta name="x-demo" content="normal">';
}, 10, 'plugin:demo');
Hook::addAction('head_end', function () {
echo '<meta name="x-demo" content="late">';
}, 20, 'plugin:demo');
$hooks = Hook::getOwnerHooks('plugin:demo');
$count = Hook::triggerCount('head_end', 'action');
Hook::removeOwner('plugin:demo');
说明:getOwnerHooks() 返回该 owner 注册过的 hook|type 列表;triggerCount() 在动作未被触发时为 0,触发一次后为 1;removeOwner() 会同时清掉动作与过滤器上属于该 owner 的全部回调,并从 owners 索引里删除。
案例:两种中断
Hook::addAction('demo_stage', function () {
return Hook::SIGNAL_BREAK;
}, 10, 'plugin:demo');
Hook::addAction('demo_stage', function () {
return Hook::SIGNAL_BREAK;
}, 10, 'plugin:demo');
Hook::addAction('demo_stage', function () {
echo 'next-priority-still-runs';
}, 20, 'plugin:demo');
Hook::doAction('demo_stage');
Hook::doAction('demo_stage');
Hook::addAction('demo_guard', function () {
return Hook::SIGNAL_STOP;
}, 10, 'plugin:demo');
$continued = Hook::doAction('demo_guard');
执行结果:demo_stage 在 10 优先级上的两个回调只执行了第一个,20 优先级的回调仍然执行,打印出 next-priority-still-runs;demo_guard 被 STOP 截断,$continued 为 false。
案例:halt() 终止请求
Hook::addAction('core_before_controller', function ($controller, $action) {
if ($controller === 'HomeController') {
http_response_code(503);
Hook::halt('<h1>维护中</h1>');
}
}, 3, 'plugin:demo');
Hook::halted();
halt($output) 做三件事:把内部 halted 标记置真、可选地 echo 一段输出、然后 exit。进程会真的结束,后续钩子、控制器、析构都不会执行。它只适合"这个请求不该继续"的场景(拦截页、强制下架、灰度关站);不适合做"提前返回某个片段"。
观测与调试
$all = Hook::getAllHooks();
$actions = $all['actions'];
$filters = $all['filters'];
$counts = $all['counts']['actions'];
$owners = $all['owners'];
$suspended = $all['suspended'];
想要一个可视化面板,可以照 plugins/hook_inspector 的做法——它就是拿这几个接口实现的。日常调试不必反复 print,临时挂一个 core_after_controller 回调,把 getAllHooks() 写进日志更省事。
动作全表
请求与渲染
| 钩子 | 参数 | 触发位置 |
|---|---|---|
core_before_controller | $controller, $action | 控制器实例化后、方法执行前(可拦截请求) |
core_after_controller | $controller, $action | 控制器方法执行后 |
head_end / body_end | 无 | 主题模板 {hook name="head_end"} 处 |
sidebar | $slot | {sidebar} 渲染时;另有 sidebar_1…sidebar_9 分槽钩子 |
ad_{name} | 无 | {ad name="xxx"} 渲染时,如 ad_header |
hook | 由模板传入 | {hook name="自定义名"},等同直接 doAction 该名 |
前台内容行级
| 钩子 | 参数 | 位置 |
|---|---|---|
home_recent_head | 无 | 首页"最近更新"表头末尾,用于echo一个<th> |
home_recent_cell | $item | 首页"最近更新"每一行末尾,echo <td>与之配对 |
home_recent_extra | $item | 移动主题"最近更新"信息块内部 |
home_card_item | $item | 首页卡片封面列表,每张卡片之后 |
home_rank_item | $item | 首页榜单<li>内部 |
home_random_item | $item | 首页随机推荐每条之后 |
library_item | $item | 书库列表每项信息区末尾 |
rank_item | $item | 排行榜每项信息区末尾 |
authors_item | $item | 作者列表每张卡片之后 |
novel_chapter_item | $item(章节数组) | 小说详情页章节列表每一章 |
novel_info_extra | $novel | 小说详情页信息区 |
这一组是"行级注入",用来给已有列表的每一项追加标签、角标、评分、按钮。它是直接 echo,返回值被忽略;数量不限,每项都会执行一次。home_recent_head 与 home_recent_cell 是成对用的——加一列就同时加表头与单元格,否则表格会错位。
Hook::addAction('library_item', function ($item) {
$score = isset($item['rating']) ? (float)$item['rating'] : 0;
if ($score <= 0) return;
echo '<div class="novel-tag">评分 ' . number_format($score, 1) . '</div>';
}, 10, 'plugin:demo');
业务事件
| 钩子 | 参数 | 时机 |
|---|---|---|
user_login_success | $user, $_POST | 登录成功 |
user_register_success | $user, $_POST | 注册成功 |
user_profile_saved | $userId, $_POST | 用户资料保存后 |
author_novel_published | $novelId, $userId, $_POST | 作者发布作品 |
author_chapter_published | $novelId, $chapterId, $_POST | 作者发布章节 |
form_saved_{formKey} | $entityType, $entityId, $post | 插件扩展表单保存后 |
plugin_page_{id}_{page} | $controller | 前台插件页 require 之前 |
cron_run | 无 | 定时任务每轮开始时 |
db_after_insert | $id, $data, $table | 模型插入成功后 |
db_after_update | $affected, $where, $table | 模型更新后 |
db_after_delete | $affected, $where, $table | 模型删除后 |
后台界面
| 钩子 | 参数 | 位置 |
|---|---|---|
admin_head | 无 | 后台 <head> 内 |
admin_login_after_form / admin_login_footer | $action | 登录表单下方 / 登录页底部 |
admin_content_top / admin_content_bottom | $action | 内容区上下边缘(每个后台页都触发) |
admin_sidebar_top / admin_sidebar_bottom | 无 | 侧边栏顶部 / 底部 |
admin_footer | 无 | 后台页脚 |
admin_settings_after | 无 | 系统设置页末尾 |
admin_dashboard_top / admin_dashboard_stats_after / admin_dashboard_bottom | 无 | 仪表盘三段插入位 |
admin_novel_edit_extra | $novel | 作品编辑页扩展字段区 |
admin_chapter_edit_extra | $chapter, $novelId | 章节编辑页扩展字段区 |
admin_user_edit_extra | $user | 用户编辑页扩展字段区 |
admin_novel_edit_saved | $id, $_POST | 作品保存后 |
admin_chapter_edit_saved | $chapterId, $novelId, $_POST | 章节保存后 |
admin_user_edit_saved | $userId, $_POST | 用户保存后 |
admin_{tab}_row_actions | 列表行数据 | 行操作列:novels / chapters / categories / authors / users / orders / ads / announcements / vip_review / withdraw / volumes |
admin_{tab}_row_actions 的参数不统一:chapters 与 volumes 会多传一个 $novelId,其余只传行数组。回调签名写成 function ($row, $extra = 0) 最稳。
过滤器
名称、参数与触发位置的全量索引见 27 章嵌入点总表;这一章讲写法:返回什么、什么时候会被跳过、改错会怎样。
过滤器是"改写型"嵌入点:框架把一个值交给你,你返回新值,框架用新值继续。这是唯一能改变框架行为的正规途径——改路由、改 SQL 片段、改输出 HTML、加后台菜单,全靠它。
Hook::addFilter(string $hook, callable $callback, int $priority = 10, ?string $owner = null): void
Hook::applyFilters(string $hook, $value, ...$args)
回调的第一个参数永远是当前值,后面的参数是框架附带的上下文。链条是串联的:A 的返回值是 B 的输入。返回 null 不会覆盖原值,返回 SIGNAL_STOP 会以"此刻已累积的值"结束整条链。
案例:注册自定义路由
<?php
if (!defined('PLUGIN_BOOT')) exit;
Hook::addFilter('router_routes', function ($routes) {
$routes[] = array('pattern' => '#^demo/probe$#', 'handler' => 'DemoProbeController@index');
return $routes;
}, 10, 'plugin:demo');
require_once __DIR__ . '/controllers/DemoProbeController.php';
效果:过滤器返回的数组里出现 ['pattern' => '#^demo/probe$#', 'handler' => 'ProbeController@index'] 后,Router::dispatch('/demo/probe') 命中该 handler 并解出参数。Router::dispatch 内部先把默认路由与注册路由合并,再逐条 preg_match,命中的捕获组按顺序作为方法参数传入。
要点:pattern 必须是完整正则(带定界符);控制器类必须已经加载——在 main.php 里 require 自己的控制器文件即可,框架不会替你找。dispatch 会先剥掉末尾的 .html,所以 /demo/probe.html 与 /demo/probe 等价。
案例:改书库查询条件
Hook::addFilter('library_where', function ($spec, $filters) {
if (empty($filters['hide_short'])) return $spec;
$spec['where'] .= ' AND `words` >= ?';
$spec['params'][] = 30000;
return $spec;
}, 10, 'plugin:demo');
默认值是 ['where' => '', 'params' => []],框架把 where 直接拼进 SQL、把 params 交给 PDO 绑定。所以片段里只能写固定字符与 ?,绝不能把用户输入拼进 where。
案例:改排序 SQL
Hook::addFilter('library_order_sql', function ($orderSql, $orderBy, $filters) {
if ($orderBy === 'random_pick') return 'RAND()';
return $orderSql;
}, 10, 'plugin:demo');
Hook::addFilter('rank_order_sql', function ($order, $type, $timeRange) {
if ($type === 'words') return '`words` DESC';
return $order;
}, 10, 'plugin:demo');
排序表达式最终会过 Database::sanitizeOrderExpr(),只保留字母数字、下划线、反引号、空格、括号、逗号与运算符号。写 RAND() 这类函数调用是允许的,写子查询会被剥掉。
案例:写入前改数据
Hook::addFilter('db_before_insert', function ($data, $table) {
if ($table === 'novels' && empty($data['seo_keywords'])) {
$data['seo_keywords'] = (string)($data['title'] ?? '');
}
return $data;
}, 10, 'plugin:demo');
第三个参数是模型表名(不带前缀,如 chapters);返回的数组整体替换待写入数据,未返回则原样写入。这里适合做"补默认值、做字段映射",不适合做权限判断(此时已经在写库路径上)。
案例:输出末尾注入
Hook::addFilter('output_filter', function ($html, $template) {
if (!is_string($html) || $html === '') return $html;
$flag = '<!-- injected -->';
if (strpos($html, '</body>') !== false) {
return str_replace('</body>', $flag . '</body>', $html);
}
return $html . $flag;
}, 30, 'plugin:demo');
output_filter 是 View::render() 的最后一步,参数是整页 HTML 与模板名。框架在这之后还会调用 brand_title() 追加站点后缀,所以这里插入的内容会位于后缀之前。注意两点:只做字符串级替换,不要用正则改结构;</body> 不存在时要判断兜底,否则会在 JSON 或纯文本响应后面粘一段注释。
案例:后台加菜单组
Hook::addFilter('admin_menu', function ($groups) {
if (!is_array($groups)) return $groups;
$groups[] = array(
'title' => '访客控制',
'items' => array(
array('plugin?pid=pc_gate', 'PC 访问拦截', 'fa-mobile-screen-button'),
),
);
return $groups;
}, 10, 'plugin:pc_gate');
菜单项是三元数组:[相对后台的 action, 显示名, 图标类]。action 里带 ? 与 = 也能用,实际链接由 admin_url() 拼成。菜单项就按这个形状写。
过滤器全表
| 钩子 | 入参 → 返回 | 用途 |
|---|---|---|
router_routes | $routes → $routes | 注册自定义路由 |
view_template | $template, $vars → 模板名 | 换模板(如按 UA 切手机版视图) |
view_template_dirs | [] → 目录数组 | 注册额外模板目录,加载时生效 |
view_before_render | $vars, $template → 变量数组 | 渲染前给模板塞变量 |
output_filter | $html, $template → HTML | 整页出口改写 |
db_before_insert | $data, $table → 数据 | 插入前改字段 |
db_before_update | $data, $where, $table → 数据 | 更新前改字段 |
library_where | $spec, $filters → ['where','params'] | 书库筛选条件 |
library_order_sql | $sql, $orderBy, $filters → SQL | 自定义排序 |
library_order_options | $options → 数组 | 允许的排序键白名单 |
library_order_labels | $labels → 映射 | 排序键的中文标签 |
library_filters | $filters, $request → 数组 | 追加筛选维度 |
library_status_labels / library_vip_labels | 映射数组 | 状态 / VIP 标签文案 |
rank_types / rank_type_labels / rank_order_sql | 数组 / 映射 / SQL | 榜单类型与排序 |
diy_block_where / diy_block_order_sql / diy_block_fields | 见案例 | DIY 区块取数 |
diy_status_options / diy_time_options / diy_order_options | 映射数组 | DIY 后台下拉项 |
admin_menu | $groups → $groups | 后台菜单 |
admin_plugin_pages | [] → action => 文件路径 | 挂自定义后台页 |
admin_page_title | $title, $action → 标题 | 改后台页标题 |
admin_novel_save_data | $data → $data | 作品保存前改数据 |
payment_gateways | [] → 网关数组 | 注册支付网关 |
captcha_verify | null, $input → bool | 接管验证码校验(返回非 null 即由插件裁决) |
captcha_render_html | $html, $name, $placeholder → HTML | 替换验证码控件 |
性能与安全
- 过滤器在热路径上(
library_where每次列表查询都跑),回调里不要查库、不要发网络请求。 - 拼接 SQL 片段只允许固定字符与
?;任何用户输入都必须走params。 - 输出改写类过滤器要考虑响应不是 HTML 的情况(JSON 接口、附件下载)。
- 同一条链上多个插件改写同一值时,优先级决定覆盖顺序;需要"最终生效"就把优先级设大。
扩展内核 Extension
Extension 是插件与主题共用的内核:它管"当前正在加载谁"、管清单解析、管每单元的配置、缓存与声明(菜单 / 设置项 / 侧栏 / 列表列 / 表单字段)。插件和主题两个门面类(Plugin、Theme)只是它的两套包装。
Extension::KIND_PLUGIN; // 'plugin'
Extension::KIND_THEME; // 'theme'
Extension::setDb($db); // 由 Bootstrap 注入,插件不需要自己调
Extension::db(); // 取当前 PDO 包装对象
上下文:正在加载谁
| 方法 | 返回 | 说明 |
|---|---|---|
begin($kind, $id) / end() | void | 框架在 require 入口文件前后调用;用栈实现,可嵌套 |
current() | plugin:pc_gate | 当前单元标记,Hook 与 PluginTable 靠它认 owner |
currentKind() / currentId() | 字符串 | 拆分形式 |
verify($kind, $id) | bool | 校验"当前正在加载的是不是它",用于防止被其他单元误调 |
context($kind, $id, $db) | 数组 | 入口文件中 extract 的七个变量:id / kind / info / db / path / url / extension |
加载与清单
| 方法 | 返回 | 说明 |
|---|---|---|
load($kind, $id, $db) | bool | require 入口并调用 plugin_init_{id} / theme_init;已加载则直接返回 true |
isLoaded($kind, $id) | bool | 判断是否已加载 |
info($kind, $id) | 数组 | 解析后的清单,带 24 小时文件缓存(按 mtime+size 签名) |
flushInfo($kind, $id) | void | 清清单缓存;改 XML 后必须调用 |
manifestFile($kind, $id) | 路径 | plugin.xml / theme.xml 的绝对路径 |
root($kind, $id) / url($kind, $id) | 路径 / URL | ROOT_PATH.'plugins/xxx/' 与站内访问地址 |
配置
Extension::config(Extension::KIND_PLUGIN, 'demo', 'notice', '默认文案');
Extension::setConfig(Extension::KIND_PLUGIN, 'demo', 'notice', '新文案');
Extension::conf('notice', '默认文案');
Extension::setConf('notice', '新文案');
conf() / setConf() 是"简写版",只在加载上下文内有意义(它取当前单元的 kind 与 id);写后台设置页、异步脚本时用完整形式,显式传 id。
缓存:按单元隔离
Extension::cacheSet('stats', array('total' => 120), 600, 'plugin', 'demo');
$stats = Extension::cacheGet('stats', array(), 'plugin', 'demo');
$html = Extension::cacheRemember('block_html', 300, function () {
return '<div>cached</div>';
}, 'plugin', 'demo');
Extension::cacheForget('stats', 'plugin', 'demo');
$cleared = Extension::cacheFlush('plugin', 'demo');
键会被改写成 ext_cache_{kind}_{id}_{md5(key)},因此不同插件用同一个 'stats' 不会互相污染;cacheFlush() 返回清掉的键数量(返回 0 时表示索引里没有键,或缓存驱动未启用)。cacheReady() 为 false 时 cacheSet 返回 false、cacheGet 返回默认值,调用方不需要额外判断。
声明:菜单、设置项、侧栏、列表列、表单字段
Extension::menu(array(
array('action' => 'plugin_page?page=stats', 'label' => '统计看板', 'icon' => 'fa-chart-line', 'group' => '内容管理'),
));
Extension::setting('notice', '页脚提示', 'text', '');
Extension::setting('mode', '运行模式', 'select', 'normal', array('normal' => '常规', 'strict' => '严格'));
Extension::sidebar(3, '演示侧栏');
Extension::table('admin.novels', array(
'key' => 'demo_flag',
'label' => '标记',
'width' => '80px',
'render' => function ($row) {
return !empty($row['demo_flag']) ? '<span class="badge">是</span>' : '-';
},
));
Extension::field('novel_edit', array(
'name' => 'subtitle',
'label' => '副标题',
'type' => 'text',
'default' => '',
));
$stats = Extension::stats();
stats() 返回 ['loaded' => [...], 'menus' => n, 'settings' => n, 'sidebars' => n],可直接用于自检页面。Extension::table() 与 field() 分别转调 PluginTable::addColumn() 与 PluginForm::addField(),owner 自动记成当前插件——这也是为什么必须在插件加载上下文里声明,否则 plugin_id 为空,保存时找不到归属。
所有 Extension::* 的声明方法都是"当场登记、本次请求有效",不落库。它们必须在入口文件被 require 时执行一次;写在某个钩子回调里只会在该回调触发时才登记,后台页面可能已经渲染完了。
插件 Plugin
Plugin 负责插件的注册表、启用状态、建表、配置与视图。它与 Extension 的分工:Plugin 面向"一个插件"的业务操作,Extension 面向"任意扩展单元"的通用能力。
状态查询
| 方法 | 返回 | 说明 |
|---|---|---|
isEnabled($id) | bool | 注册表里 status=1 且已加载 |
enabledIds() | 数组 | 本次请求实际加载的插件 id 列表 |
all() | 数组 | 已加载插件的清单数组,键为 id |
manifest($id) | 数组 | 单个插件解析后的清单(未启用也能读) |
isRegistered($id) / registryVersion($id) | bool / 字符串 | 注册表里的安装状态与版本 |
verifyId($id) / currentId() | bool / 字符串 | 当前加载上下文判断 |
hasAdminPage($id) | bool | plugins/{id}/admin.php 是否存在 |
isEnabled() 只看启用标记:启用返回 true,停用返回 false。而 hasAdminPage() 判断的是 admin.php 是否存在,与启用状态无关——所以一个插件停用后 hasAdminPage() 仍可能为 true,只是用户进不去它的功能页。
配置读写
Plugin::setConfig('notice', '本站启用 CDN', 'demo');
$notice = Plugin::config('notice', '默认值', 'demo');
$notice2 = Plugin::config('notice', '默认值');
Plugin::flushConfigCache('demo');
省略第三个参数时取当前加载的插件,因此在 main.php 里可以简写;在页面、控制器、CLI 脚本里必须显式传 id,否则会读到空。flushConfigCache() 用于配置改动后清掉进程内缓存(同一请求里先写后读的场景)。
建表:自动加插件前缀
Plugin::createTable('items', array(
'id' => 'INT(11) NOT NULL AUTO_INCREMENT',
'title' => 'VARCHAR(120) NOT NULL DEFAULT ""',
'score' => 'INT(11) NOT NULL DEFAULT 0',
'created' => 'DATETIME DEFAULT CURRENT_TIMESTAMP',
'__PRIMARY__' => 'id',
));
Plugin::addColumn('items', 'extra', 'VARCHAR(64) NOT NULL DEFAULT ""');
Plugin::dropColumn('items', 'extra');
Plugin::dropTable('items');
注意:在没有插件上下文时建 items,拼出来的表名是 En_items(插件前缀为空,只拼 DB 前缀);在插件上下文里建同名表则是 En_pc_gate_items。结论:建表必须发生在插件加载上下文内,否则前缀里没有插件 id。所以建表代码放 plugin_install_{id},由框架在加载后调用。
视图:只在加载上下文可用
Plugin::view($template, $data) 用内部记录的当前插件 id 去拼 plugins/{id}/views/。这个值在入口文件加载结束时被清空,所以它只在两个位置有效:main.php 顶层,以及 plugin_init_{id}() 函数体内(框架是先 require 再调 init,最后才结束上下文)。
function plugin_init_demo($db): void
{
$defaultHtml = Plugin::view('stats.tpl', array('total' => 0, 'today' => 0));
Hook::addFilter('view_before_render', function ($vars, $template) use ($defaultHtml) {
$vars['demo_stats_html'] = $defaultHtml;
return $vars;
}, 10, 'plugin:demo');
}
需要"运行时按数据渲染",把模板目录登记给视图层,之后用 View::fetch():
function plugin_init_demo($db): void
{
View::addTemplateDir(ROOT_PATH . 'plugins/demo/views');
Hook::addAction('admin_dashboard_bottom', function () {
echo View::fetch('stats.tpl', array(
'total' => (int)Plugin::config('total', 0, 'demo'),
'today' => 6,
));
}, 10, 'plugin:demo');
}
反例:如果在钩子回调里直接写 Plugin::view('stats.tpl', $data),会得到空字符串——此时当前插件 id 已被清空,函数找不到模板目录。这个错误不会抛异常,只会静默返回空,表现为"后台多了一块空白"。排查时优先怀疑这一条。
案例:完整的插件数据闭环
<?php
if (!defined('PLUGIN_BOOT')) exit;
function plugin_install_demo($db): void
{
if (!$db->tableExists('demo_items')) {
Plugin::createTable('demo_items', array(
'id' => 'INT(11) NOT NULL AUTO_INCREMENT',
'title' => 'VARCHAR(120) NOT NULL DEFAULT ""',
'score' => 'INT(11) NOT NULL DEFAULT 0',
'__PRIMARY__' => 'id',
));
$db->addIndex('demo_items', 'idx_score', array('score'));
}
Plugin::setConfig('per_page', '20', 'demo');
}
function plugin_init_demo($db): void
{
View::addTemplateDir(ROOT_PATH . 'plugins/demo/views');
Hook::addFilter('admin_menu', function ($groups) {
$groups[] = array('title' => '演示', 'items' => array(
array('plugin_page?pid=demo&page=stats', '统计看板', 'fa-chart-line'),
));
return $groups;
}, 10, 'plugin:demo');
}
启用、卸载与升级
| 方法 | 返回 | 行为 |
|---|---|---|
enable($id, $db) | bool | 校验清单与依赖,跑 plugin_install_{id}(首次),写注册表 status=1 |
disable($id, $db) | bool | 注册表 status=0,不删数据、不删表 |
runUninstall($id, $db) | 数组 | 调用 plugin_uninstall_{id},返回 ['ok','msg'] |
maybeUpgrade($id, $db) | void | 磁盘版本高于注册表版本时,调用 plugin_upgrade_{id} 并更新版本 |
delete($id, $db) | 数组 | 卸载 + 删目录 + 清注册表 |
purgeConfig($id) / purgeTables($id) | void | 清配置行 / 清带前缀的表 |
scanAll() | 数组 | 扫描磁盘上全部插件目录,含 installed / enabled 标记 |
validate($id) | 数组 | 安装前静态校验(id、清单、依赖) |
升级钩子的签名是 plugin_upgrade_demo($db, $oldVersion, $newVersion);没有定义时框架只更新版本号,不动数据。
主题 Theme
主题的能力比插件窄,但边界更清晰:一套主题提供模板、注册钩子、声明设置项,并在安装 / 卸载 / 升级三个时点执行自己的迁移代码。主题靠清单里的 <type> 声明自己能设到哪一端:pc、mobile,或 both(响应式,两端都能设)。
状态与选择
Theme::activePc();
Theme::activeMobile();
Theme::isActive('default');
Theme::isRegistered('default');
Theme::installedIds();
Theme::manifest('default');
Theme::configFields('default');
Theme::typeOf('default');
Theme::supports('both', 'mobile');
Theme::typeLabel('pc');
Theme::scanAll();
默认安装只带两套主题:PC 用 default,移动端用 defaultm。activePc() / activeMobile() 返回当前启用的 id,manifest('default') 返回解析后的清单数组;configFields('default') 返回空数组是正常现象——该主题目录没有 config.php,清单里声明了 <config> 但文件缺失时,框架容错为"没有设置项",不报错。scanAll() 会给每个主题附 installed / active_pc / active_mobile / has_config / supports_pc / supports_mobile 六个标记,后台靠 supports_* 决定显示"设为PC"还是"设为手机"按钮。typeOf('default') 取回 pc,supports('both','mobile') 为真,typeLabel('pc') 返回后台展示用的 PC。
主题配置
<?php
return array(
array('name' => 'reads_per_page', 'label' => '每页显示条数', 'type' => 'number', 'default' => 12),
array('name' => 'show_rank', 'label' => '显示排行榜', 'type' => 'switch', 'default' => 1),
array('name' => 'list_layout', 'label' => '列表布局', 'type' => 'select', 'default' => 'grid',
'options' => array('grid' => '网格', 'list' => '列表')),
array('name' => 'footer_note', 'label' => '页脚备注', 'type' => 'textarea', 'default' => ''),
);
支持的 type:text(默认)、number、switch、select(需 options)、textarea、password。保存时按类型归一:number 转 float、switch 转 0/1、其余 trim 字符串。POST 字段名固定为 tcfg[name]。
Theme::config('reads_per_page', 12);
Theme::config('reads_per_page', 12, 'defaultm');
Theme::setConfig('reads_per_page', 20);
配置落在 settings 表,键名格式 theme_config.{theme}.{key},值是字符串。默认值由 config.php 定义,不在库里时返回默认,不会自动写库。
入口文件 include.php
<?php
View::addTemplateDir(ROOT_PATH . 'templates/demo/views');
Hook::addFilter('view_before_render', function ($vars, $template) {
$vars['theme_per_page'] = (int)Theme::config('reads_per_page', 12);
return $vars;
}, 10, 'theme:demo');
Hook::addAction('head_end', function () {
echo '<link rel="stylesheet" href="' . Security::h(Extension::url('theme', 'demo')) . 'css/main.css">';
}, 10, 'theme:demo');
function theme_init($db): void
{
$db->find('settings', array('key' => 'theme_config.demo.reads_per_page'));
}
Theme::loadInclude('demo') 执行后 Extension::isLoaded('theme','demo') 为 true;Theme::verifyId('demo') 只在加载期内为 true。theme_init($db) 是主题的初始化钩子,每次加载执行一次,适合做"表结构就绪检查"与"默认配置补齐",不要在这里做重活。
安装、启用、卸载
function theme_install_demo($db) { }
function theme_uninstall_demo($db) { }
function theme_upgrade_demo($db, $oldVersion, $newVersion) { }
也可以写成不带 id 的通用名 theme_install / theme_uninstall / theme_upgrade(框架优先找带 id 的)。插件与主题的生命周期只走函数,没有单独的 install.php 这类文件——装、卸、升级的逻辑一律写进入口文件。
| 方法 | 返回 | 说明 |
|---|---|---|
install($id, $db) | ['ok','msg'] | 校验 id 与清单、依赖,跑 theme_install_{id},写注册表 |
enable($id, $type, $db) | ['ok','msg'] | $type 只能是 pc 或 mobile;清单类型与目标端不符直接拒绝(pc 主题不能设手机、mobile 主题不能设 PC、both 两端都行),通过后改 active_theme / mobile_theme |
disableMobile($db) | ['ok','msg'] | 清空 mobile_theme,手机端跟随 PC 主题 |
uninstall($id, $db) | ['ok','msg'] | 拒绝默认主题、拒绝卸载当前启用主题;跑卸载钩子后删目录、清配置、清 owner 钩子 |
delete($id, $db) | ['ok','msg'] | 未安装时直接删目录,否则等同 uninstall |
maybeUpgrade($id, $db) | void | 版本升高时触发主题升级函数 |
类型决定它能设到哪一端。<type> 只能是 pc / mobile / both 三个单值。mobile_theme 为空时手机端跟随 PC 主题;要两端共用一套主题就声明 both,在自己样式表里用断点处理窄屏。声明为 pc 的主题不要加移动端媒体查询——那会和手机主题互相打架。
数据层
四层结构:Database(PDO 包装 + 表结构操作)、QueryBuilder(链式查询)、PluginDB(插件表静态助手,自动加插件前缀)、Model(系统表的静态模型)。插件开发者用前三层就够。
表前缀:三条规则,记错必挂
| 你要做的事 | 写法 | 真实表名 |
|---|---|---|
| 操作系统表(novels、chapters、settings…) | $db->select('novels', …) / $db->from('novels') | En_novels |
操作自己用 Plugin::createTable('items') 建的表 | PluginDB::find('items', …) / $db->from('pc_gate_items') | En_pc_gate_items |
| 手写 SQL | 'SELECT * FROM ' . $db->table('novels') | `En_novels`(含反引号) |
最容易踩的坑:Plugin::createTable('items') 建出来的是 En_pc_gate_items,而 $db->from('items') 查的是 En_items——两张不同的表,后者不存在,会报 Table 'xxx.items' doesn't exist。QueryBuilder 只加全局前缀(DB_PREFIX),不加插件前缀;插件前缀只由 PluginDB 的静态方法补。
Database
| 方法 | 返回 | 说明 |
|---|---|---|
table($t) | 字符串 | 拼成 `En_xxx`,手写 SQL 专用 |
from($t, $alias='') | QueryBuilder | 链式查询入口,自动加全局前缀 |
query($sql, $params=[]) | PDOStatement | 预编译执行,不自动加前缀 |
select($t, $where=[], $order='', $limit=0, $offset=0, $fields='*') | 数组 | 简单列表查询 |
find($t, $where=[], $fields='*') | ?数组 | 单行,无结果返回 null |
findById($t, $id, $fields='*') | ?数组 | 主键查询 |
count($t, $where=[]) | int | 计数 |
insert($t, $data) | int | 返回自增 id |
batchInsert($t, $rows) | int | 批量插入,返回影响行数 |
update($t, $data, $where) | int | 影响行数 |
delete($t, $where) | int | 影响行数 |
increment/decrement($t, $field, $amount=1, $where=[]) | int | 原子加减 |
createTable($t, $columns, $engine='InnoDB', $charset='utf8mb4') | bool | 列定义数组,主键用 '__PRIMARY__' => 'id' |
dropTable / truncate / tableExists / getColumns | bool / 数组 | 建表维护 |
addColumn / modifyColumn / dropColumn | bool | 列变更,第二参数为列名,第三为完整定义 |
addIndex($t, $name, $columns) / dropIndex | bool | 普通索引;唯一索引请直接写列定义里的 UNIQUE |
beginTransaction / commit / rollBack | bool | 事务 |
sanitizeOrderExpr($expr) | 字符串 | 静态;过滤排序表达式,只留字母数字、下划线、反引号、空格、括号、逗号与比较运算符 |
$where 是等值数组:array('status' => 1, 'pid' => 3)。需要范围、模糊、IN 时改用 QueryBuilder。
QueryBuilder
$rows = $db->from('novels')
->where('`status` = ?', array(1))
->where('`created_at` >= ?', array('2026-01-01'))
->whereIn('category_id', array(3, 7, 11))
->whereLike('title', '%剑%')
->orderBy('`id` DESC')
->limit(20, 40)
->get();
$one = $db->from('novels')->where('`id` = ?', array(9))->first();
$n = $db->from('novels')->where('`status` = ?', array(1))->count();
where() 的签名是 where(string $condition, array $params = [])——不是 where('字段', '操作符', '值')。条件串里用 ? 占位,字段名建议用反引号包裹。orderBy() 接表达式字符串,来源可控时才拼变量。
| 方法 | 说明 |
|---|---|
select($fields) / selectRaw($sql) / distinct() | 字段选择 |
where / orWhere / whereIn / whereNotIn / whereNull / whereNotNull / whereBetween / whereLike | 条件 |
join($table, $alias, $on) / leftJoin / rightJoin | 联表,$on 为原始条件串 |
groupBy($expr) / having($cond, $params=[]) | 分组 |
orderBy($expr) / limit($n, $offset=0) | 排序与分页 |
get() / first() / count() / paginate($perPage=20, $page=1) | 取值 |
分页:两种返回形状,别记混
| 来源 | 返回键 |
|---|---|
QueryBuilder::paginate() | list / total / page / perPage / totalPages |
PluginDB::paginate() 与 PluginDB::search() | rows / total / pages / page / pageSize |
$page = max(1, (int)($_GET['page'] ?? 1));
$data = $db->from('pc_gate_items')->where('`score` > ?', array(0))->paginate(20, $page);
$pager = View::getSmarty()->fetch('function.pagination', array(
'total' => $data['total'],
'page' => $data['page'],
'perpage' => $data['perPage'],
));
PluginDB:插件表的静态助手
PluginDB::insert('items', array('title' => '第一条', 'score' => 8));
$row = PluginDB::findById('items', 3);
$all = PluginDB::all('items', array('score >' => 5), '`id` DESC', 10);
$hit = PluginDB::search('items', '剑', array('title'), 1, 20, '`id` DESC');
$p = PluginDB::paginate('items', array('status' => 1), 2, 15);
PluginDB 的表名参数写"插件内的短名"(items),它会补成 {pluginId}_items 再交给 Database。search() 的 $fields 是参与模糊匹配的列名数组。paginate() 参数顺序是 (表, 条件, 页码, 每页, 排序)——与 QueryBuilder 的 (每页, 页码) 相反。
事务
$db->beginTransaction();
try {
foreach ($rows as $row) {
PluginDB::insert('items', $row);
}
$db->commit();
} catch (\Throwable $e) {
$db->rollBack();
Logger::plugin('demo', 'import failed', array('err' => $e->getMessage()));
}
事务期间不要在循环里查缓存写缓存,容易在回滚后留下脏数据。
Model 与章节分表
系统表有现成的 Model 子类(NovelModel、ChapterModel 等),静态方法 findById / find / all / paginate / count / sum / create / update / updateById / delete / deleteById / increment / decrement,表名由子类的 static::$table 声明。插件读系统数据可以直接用它们,也可以走 Database;写系统数据建议走 Model,因为里面带了业务规则。
章节表按 ChapterShard 分片:SHARD_SIZE = 1000000,基表 chapters,之后是 chapters_1…。shardIndex($chapterId) 算出分片号,shardTable($chapterId) 给出真实表名,groupIdsByShard($ids) 把一批章节 id 按分片归类。插件做跨章节统计时不要假设只有一张 chapters 表。
缓存 Cache
四个驱动,一个接口。是否启用由 config/config.php 里的 CACHE_ENABLE 决定,驱动由 CACHE_DRIVER 决定,默认 TTL 由 CACHE_TTL 决定(默认 300 秒)。驱动不可用时自动回退文件驱动,不会抛异常。
| 驱动 | 可用条件 | 适用 |
|---|---|---|
file | 始终可用 | 单机、无扩展环境,最稳 |
memcached | extension_loaded('memcached') | 多进程共享 |
redis | extension_loaded('redis') | 多机共享、需主动失效 |
yac | 扩展已装且 yac.enable 为真(CLI 还需 yac.enable_cli=1) | 进程内共享内存,最快 |
方法
Cache::isEnabled();
Cache::driverType();
Cache::drivers();
Cache::get('home_hot_list');
Cache::set('home_hot_list', $list, 600);
Cache::delete('home_hot_list');
Cache::flush();
Cache::remember('home_hot_list', 600, function () use ($db) {
return $db->select('novels', array('status' => 1), '`views` DESC', 10);
});
键长上限 32 字节,超长会被改写成 h{md5前31位},所以同一个超长键每次都会落到同一位置,不会失效,但不可读。写代码时尽量让键短而语义清楚。
| 层 | 键形态 | 什么时候用 |
|---|---|---|
Cache | 你给的原始键 | 站点级公共数据:首页列表、榜单、分类树 |
Extension::cache* | ext_cache_{kind}_{id}_{md5(key)} | 插件/主题私有数据,可用 cacheFlush 一键清空 |
插件一律用 Extension::cache*。这样卸载插件时 cacheFlush('plugin', $id) 能清干净,也不会和别人撞键。
TTL 与失效
$ttl | 行为 |
|---|---|
省略 / null | 用 CACHE_TTL(默认 300 秒) |
0 或负数 | 永不过期,四种驱动语义一致 |
| 正整数 | 秒数 |
| 场景 | 框架自动做了什么 |
|---|---|
| 插件停用 | 清掉本插件全部 ext_cache_* 键 |
| 插件删除 | 先跑卸载钩子,再清配置与缓存 |
改 plugin.xml / theme.xml | 清单缓存键含 mtime+size,改完立刻换键,旧键按 TTL 自然过期 |
| 后台"清空缓存" | 全量 Cache::flush() |
系统自己也在用缓存,了解这些键可以避免"为什么改了设置没生效":settings_all(全站配置,3600 秒,保存设置后自动删)、library_*(书库列表第 1–10 页,300 秒)、novel_rank_*(各榜单 TOP,600 秒)、official_notices(官网公告,3600 秒)。
文件驱动的落盘与保护
文件驱动写到 data/cache/md5(key).cache.php,文件首行是 <?php exit; ?>。这样即使有人猜到路径直接访问,PHP 会立即退出、输出空内容,不会泄露数据。这也解释了为什么缓存文件必须是 .php 后缀——它靠"被当代码执行"来实现自保护,而不是靠 Web 服务器配置。
案例:列表缓存与主动失效
function demo_hot_list($db): array
{
return Extension::cacheRemember('hot_list', 600, function () use ($db) {
return $db->select('pc_gate_items', array(), '`score` DESC', 0, 0);
}, 'plugin', 'demo');
}
Hook::addAction('db_after_update', function ($table, $data, $where) {
if ($table === 'pc_gate_items') {
Extension::cacheForget('hot_list', 'plugin', 'demo');
}
}, 10, 'plugin:demo');
不要缓存的东西:登录态、CSRF token、用户私有数据、验证码、任何"按用户区分"的内容。缓存键如果拼了用户 id,键会爆炸且很难失效——这类数据直接查库,通常也够快。
日志 Logger
统一日志只有一个入口:Logger。框架自己的日志走七个固定通道,扩展的日志落在各自的插件 / 主题子目录;文件名一律由框架生成(id 或通道名 + 12 位随机 hex),单文件超过 2MB 自动轮转。插件不要自己开日志文件,也不要往系统通道里写。
系统通道
app admin upgrade appcenter cron api security
Logger::channels(); // 返回上面七个
这七个通道属于框架自身,落盘在 data/logs/ 顶层,文件名 {channel}.{12位hex}.log。插件与主题的名字不在这份名单里——扩展日志有自己的目录,见下一节。通道名还要匹配 ^[a-z0-9_\-]{1,32}$,不在白名单内 write() 直接返回 false,不落盘、不建目录。
插件与主题日志
data/logs/
├── app.9f3c1a7b2d54.log 系统通道,共 7 个
├── security.d663a6b0c733.log
├── plugins/
│ └── pc_gate/
│ └── pc_gate.558f5ab8278d.log 插件日志
└── themes/
└── mytheme/
└── mytheme.f3ddf37dea0b.log 主题日志
| 方法 | 作用 |
|---|---|
plugin($id, $content, $context) | 写 data/logs/plugins/{id}/{id}.{hex}.log |
theme($id, $content, $context) | 写 data/logs/themes/{id}/{id}.{hex}.log |
readPlugin($id, $lines) / readTheme($id, $lines) | 按文件 mtime 读末尾 N 行,0 为不限 |
clearPlugin($id) / clearTheme($id) | 只删自己目录里的文件 |
extensions() | 返回 ['plugins' => [...], 'themes' => [...]],列出已有日志的扩展 id,供后台做日志列表 |
$id 必须是合法标识(a-z0-9_-)且 plugins/{id} 或 templates/{id} 真实存在,否则方法返回 false——不存在的 id 不会凭空建目录。子目录名就是扩展 id,卸载时 clearPlugin('你') 只清自己的文件,别的插件、主题、系统通道都不受影响。
写、读、清
Logger::plugin('pc_gate', 'blocked', array('ip' => $ip, 'url' => $url));
Logger::theme('mytheme', 'config saved');
$lines = Logger::readPlugin('pc_gate', 200);
$all = Logger::readPlugin('pc_gate', 0);
Logger::clearPlugin('pc_gate');
系统通道用同名方法 write() / read() / clear(),但只接受那七个通道名。落盘格式一行一条:[2026-11-15 10:22:31] blocked {"ip":"..."};正文里的换行压成 | ,一条日志不跨行。读出来的行按文件 mtime 排列,配合 array_reverse 就是"最新在上"。
敏感字段自动掩码
password passwd pwd token secret cookie authorization api_key apikey private_key
Logger::plugin('demo', 'login', array('user' => 'demo', 'password' => '123456'));
// 落盘: [..] login {"user":"demo","password":"***"}
掩码只对 context 数组按键名生效,嵌套数组会递归处理。正文参数 $content 是纯字符串,框架不解析它——所以不要把密码拼进正文。
文件与轮转
| 项 | 规则 |
|---|---|
| 目录 | 系统通道 data/logs/;插件 data/logs/plugins/{id}/;主题 data/logs/themes/{id}/ |
| 文件名 | {通道或id}.{12位随机hex}.log,新建时随机 |
| 轮转阈值 | 2 MB(MAX_BYTES = 2097152) |
| 轮转动作 | 旧文件改名为 {name}.{hex}.{YmdHis}.log,再新建一个随机名文件 |
| 并发 | 追加写 + LOCK_EX |
日志文件的 Web 可访问性
日志目录在站点根内,目录列表是关闭的,但已知完整文件名的文件可以被直接下载。文件名里的 12 位随机 hex 就是唯一屏障:换掉 hex 就等于换了一把钥匙。
| 请求 | 响应 | 含义 |
|---|---|---|
/data/logs/ | 403 | 没有目录列表,无法枚举文件名 |
/data/logs/plugins/ | 403 | 同上,扩展子目录也不可枚举 |
/data/logs/plugins/{id}/{id}.{hex}.log | 200 | 知道完整路径才能读;hex 无法穷举 |
所以不要自己 file_put_contents() 写日志,也不要给文件起固定名。要记日志调 Logger::plugin() / Logger::theme(),读用 readPlugin() / readTheme(),卸载时 clearPlugin() / clearTheme()——路径、文件名、轮转都由 Logger 决定。
日志红线:
1. 不得占用 app / admin / upgrade 这些系统通道——那是框架自己的记录,扩展往里写会让排查时无法区分来源。
2. 不得自建日志文件、不得指定路径、不得用固定文件名,一律走 Logger::plugin() / Logger::theme()。
3. 不得把日志写成 .php 后缀(那类后缀留给缓存、限流这种"系统生成、格式固定"的文件,日志内容外部可控,不能挂执行后缀)。
4. 不得记录密码、token、cookie、完整手机号、完整邮箱、身份证号。拿不准就不记。
5. 不得把 $_POST 整个丢进 context——里面通常就有密码字段,掩码只认键名,拼进正文就漏了。
案例:插件内的日志三件套
function demo_task_run($db): void
{
$start = microtime(true);
try {
$n = demo_import($db);
Logger::plugin('demo', 'import ok', array('rows' => $n, 'cost' => round(microtime(true) - $start, 3)));
} catch (\Throwable $e) {
Logger::plugin('demo', 'import failed', array('err' => $e->getMessage(), 'line' => $e->getLine()));
}
}
$rows = array_reverse(Logger::readPlugin('demo', 50));
function plugin_uninstall_demo($db): void
{
Logger::clearPlugin('demo');
}
清的是自己的目录。clearPlugin('demo') 只动 data/logs/plugins/demo/,别的插件、主题、系统通道全都不受影响——这正是扩展日志必须按 id 分目录的原因。
邮件 MailService
邮件走 PHPMailer + SMTP,配置全部来自 settings 表,代码里不写死任何服务器参数。MailService 是实例类,必须先 new。
SMTP 配置项
| 设置键 | 说明 |
|---|---|
smtp_host | SMTP 主机,默认 localhost |
smtp_port | 端口;465 自动走 ssl,587 自动走 tls,其他端口不加密 |
smtp_user | 账号 |
smtp_pass | 密码 |
smtp_from | 发件地址;非法时回退到 smtp_user,再回退 noreply@localhost |
smtp_fromname | 发件人名称,默认取 site_name |
发送
$mail = new MailService();
$r = $mail->send('reader@example.com', '新章节已更新', '<p>《示例》第 12 章已发布。</p>');
if (empty($r['ok'])) {
Logger::plugin('demo', 'mail failed', array('msg' => $r['msg'] ?? ''));
}
$r2 = $mail->sendVerifyCode('reader@example.com');
成功只返回 ['ok' => true],失败返回 ['ok' => false, 'msg' => '邮件发送失败']。失败不抛异常,所以调用方必须检查 ok,否则会静默丢信。sendVerifyCode() 会先校验邮箱格式(非法直接返回"邮箱格式不正确"),再生成 6 位数字验证码并写入 EmailVerify 存储,然后发信。
案例:注册成功后发欢迎信
Hook::addAction('user_register_success', function ($userId, $user) {
if (empty($user['email'])) return;
if ((string)SettingModel::get('mail_welcome', '1') !== '1') return;
$site = Security::h((string)SettingModel::get('site_name', '本站'));
$html = '<h3>欢迎加入 ' . $site . '</h3><p>你的账号已创建,现在可以收藏与追更了。</p>';
$r = (new MailService())->send($user['email'], '欢迎加入 ' . $site, $html);
if (empty($r['ok'])) {
Logger::plugin('demo', 'welcome mail failed', array('uid' => $userId));
}
}, 10, 'plugin:demo');
三条纪律:邮件正文里所有用户可控内容必须 Security::h() 转义;不要把 SMTP 密码写进代码或日志;批量发信要分批并间隔,同步发送 100 封会把请求拖到超时。
设备判断与蜘蛛识别
框架提供三个全局函数做设备判断,全部可传自定义 UA(不传则读 $_SERVER['HTTP_USER_AGENT'])。判定规则只有一份,插件调用与框架内部走的是同一套逻辑。
device_type(); // 'mobile' | 'pc'
is_mobile();
is_pc();
is_pc('Mozilla/5.0 (Windows NT 10.0; Win64; x64)'); // true
is_mobile('Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X)'); // true
device_type('Mozilla/5.0 (iPad; CPU OS 15_0 like Mac OS X)'); // 'mobile'
判断顺序
内部逻辑分两步,顺序不能颠倒:
- 先匹配"桌面 / 平板"特征:
iPad|Tablet|PlayBook|Silk|Macintosh|Windows NT|Windows OS。命中这些通常判 PC。 - 但 UA 里含
iPad时不直接判 PC,继续往下走——因为 iPad 的 UA 同时带Macintosh和Mobile特征。 - 再匹配移动特征:
Android|iPhone|iPod|Symbian|Windows Phone|Mobile|HarmonyOS|MiuiBrowser,以及MicroMessenger同时带iPhone|Android(微信内置浏览器)。命中任一即 mobile。 - 都不命中 → PC。
这套顺序解决了"平板被误判成手机"和"iPad 被误判成 Mac"两个常见问题。想按自己的规则判(例如把平板单独算一类),拿 UA 自己写,is_mobile 只给"二选一"的答案。
蜘蛛识别
$isBot = CommonService::isSpider();
if (CommonService::isSpider()) {
Logger::plugin('demo', 'bot visit', array('ua' => substr((string)($_SERVER['HTTP_USER_AGENT'] ?? ''), 0, 120)));
}
它直接读 $_SERVER['HTTP_USER_AGENT'],不接受参数。要做"UA + 反查 DNS"这类更强校验,用 Network 自己发请求,或参考 pc_gate 插件的 spider_mode 实现(它支持 off / ua / ua_dns 三档)。
案例:按设备切换列表条数
Hook::addFilter('view_before_render', function ($vars, $template) {
if (strpos($template, 'library') === false) return $vars;
$per = is_mobile() ? 8 : 20;
if (!empty($vars['list']) && is_array($vars['list'])) {
$vars['list'] = array_slice($vars['list'], 0, $per);
}
$vars['per_page'] = $per;
return $vars;
}, 10, 'plugin:demo');
设备判断是"看 UA 字符串",不保证准确:UA 可以伪造,新设备也会漏判。不要用它做权限或安全判断,只用于展示层适配。
二维码:后端生成,前端解码
二维码能力被刻意拆成两半:生成在 PHP 侧(服务端出图,保证每个访客拿到同一张、可缓存、可落盘),解码在浏览器侧(jsQR,读摄像头或上传的图片)。PHP 侧没有解码器,也不打算加——那需要额外扩展或臃肿的纯 PHP 实现,与"零环境依赖"冲突。
生成:五个函数
| 函数 | 返回 | 用途 |
|---|---|---|
qr_code_library() | bool | 运行环境是否具备生成能力(依赖 vendor/QR/phpqrcode.php) |
qr_code_png($content, $opts=[]) | ?string | PNG 二进制;失败返回 null |
qr_code_data_uri($content, $opts=[]) | string | data:image/png;base64,…,直接塞 <img src> |
qr_code_save($content, $absPath, $opts=[]) | bool | 落到绝对路径,用于生成固定文件 |
qr_code_color($color, $default) | int | 把 #rrggbb / 颜色名转成 GD 的整数色值;非法时返回 $default |
$opts 支持尺寸、边距、前景色 / 背景色(键名见下例)。内容长度上限 500 字符,超长会被库拒绝,所以别把整段 JSON 塞进去——存短链或 id。
if (!qr_code_library()) return;
$opts = array('size' => 6, 'margin' => 2, 'foreground' => '#1b1b1b', 'background' => '#ffffff');
$bin = qr_code_png('https://example.com/read/128.html', $opts);
$uri = qr_code_data_uri('https://example.com/read/128.html', $opts);
$ok = qr_code_save('https://example.com/read/128.html', ROOT_PATH . 'data/qr/128.png', $opts);
模板标签
{qr content=$read_url assign="qr_uri"}
<img src="{$qr_uri}" alt="扫码阅读">
assign 把 data URI 放进模板变量,避免在模板里直接输出 base64 长串(那样会把模板源码撑爆,也不利于缓存)。
解码:在前端做
参考实现:templates/default/views/author/withdraw.tpl。它引入 assets/js/jsqr.js,用 <canvas> 画图、getImageData 取像素,再调 jsQR(imgData.data, w, h) 拿结果。这段逻辑可以直接抄进插件页面。
<input type="file" id="qrFile" accept="image/*">
<pre id="qrOut"></pre>
<script src="/assets/js/jsqr.js"></script>
<script>
(function () {
var input = document.getElementById('qrFile');
var out = document.getElementById('qrOut');
if (!input || !out || typeof jsQR !== 'function') return;
input.addEventListener('change', function () {
var file = input.files && input.files[0];
if (!file) return;
var img = new Image();
img.onload = function () {
var c = document.createElement('canvas');
c.width = img.width;
c.height = img.height;
var ctx = c.getContext('2d');
ctx.drawImage(img, 0, 0);
var data = ctx.getImageData(0, 0, c.width, c.height);
var res = jsQR(data.data, c.width, c.height);
out.textContent = res && res.data ? res.data : '未识别到二维码';
};
img.src = URL.createObjectURL(file);
});
})();
</script>
边界写清楚:服务端只生成、不解码。需要"用户上传二维码 → 服务端读出内容"时,只能在前端解码后把结果提交给后端;后端拿到的应是普通字符串,必须按不可信输入处理(长度限制、白名单协议、Security::safeUrl 校验)。
安全 Security
所有安全原语都在 Security 静态类里。插件不要自己写 htmlspecialchars、不要自己拼 CSRF 校验、不要自己判断上传类型——用这些方法,行为才和系统一致。
输出与输入
| 方法 | 说明 |
|---|---|
h($str) | HTML 转义,等价于 htmlspecialchars + UTF-8;模板里用 |escape,PHP 里用它 |
input($key,$default=null,$type='str') | 读 $_REQUEST;$type 支持 int / float / bool / str / raw / array |
get(...) / post(...) | 同上,分别只读 $_GET / $_POST |
safeFilename($name) | 去路径、去危险字符;'../../a b.php' 得到 ab.php |
safeUrl($url) | 拒绝 javascript: 与 // 开头的地址,只放行 http(s);非法返回空串 |
raw 类型不做 trim、不转字符串——只有在你确定要原样拿数组或富文本时用,拿到后仍要自己清洗。
CSRF
<form method="post">
<?= Security::csrfField() ?>
<input type="text" name="title">
</form>
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
if (!Security::verifyCsrf()) {
exit('Invalid token');
}
}
csrfField() 输出隐藏域 _csrf,token 是 64 位 hex,存在 session 里。verifyCsrf() 先读 $_POST['_csrf'],取不到再读请求头 X-CSRF-Token,用 hash_equals 做定长比较。AJAX 提交时把 token 放请求头即可,不必塞进 body。
密码
$hash = Security::hashPassword($plain);
$ok = Security::verifyPassword($plain, $hash);
验证码
echo Security::captchaHtml('captcha', '请输入验证码');
if (!Security::verifyCaptcha(Security::post('captcha'))) {
exit('验证码错误');
}
默认配置:{"enabled":true,"length":5,"charset":"alnum","case_sensitive":false}。generateCaptcha() 直接输出 PNG(自带 Content-Type,调用后必须 exit);requireCaptcha() 返回错误文案或 null,适合在表单校验链里用;clearCaptcha() 在验证成功后清 session,防重复使用;captchaEnabled() 判断后台是否开启,关闭时不要渲染验证码块。
需要自定义渲染时挂过滤器 captcha_render_html,需要接管校验时挂 captcha_verify——两者都返回"是否通过 / 替换后的 HTML",可用于接第三方验证码。
上传
$img = Security::verifyImageUpload($_FILES['cover'], 2 * 1024 * 1024);
if ($img === null) {
exit('图片不合法');
}
$ext = $img['ext'];
$mime = $img['type'];
if (!Security::verifyZipUpload($_FILES['pack'])) {
exit('压缩包不合法');
}
verifyImageUpload() 校验大小、扩展名白名单与实际图像类型,返回 ['ext','type'],非法返回 null——不要用 $_FILES['x']['type'] 自己判,那个值由客户端提供。verifyZipUpload() 返回 bool。落盘时文件名必须过 safeFilename(),并自己拼随机前缀防止覆盖。
其它
| 方法 | 说明 |
|---|---|
sendSecurityHeaders() | 输出 X-Content-Type-Options / X-Frame-Options / Referrer-Policy / Permissions-Policy;HTTPS 且后台开启 HSTS 时追加 Strict-Transport-Security |
validPluginId($id) | ^[a-z0-9_]+$,路由与插件页入口都靠它防目录穿越 |
validateLanguagePack($content) | 校验语言包格式,返回 ['ok','errors'] |
randomToken($length=32) | 随机 token,用于一次性链接、API 密钥 |
SecurityGuard:它在你看不见的地方拦人
框架在 Bootstrap 早段执行 SecurityGuard。不带浏览器 UA 的前台请求一律 403——返回一个固定的拦截页。curl 默认 UA 是 curl/8.x,属于"无浏览器特征",会被拦。做接口联调时必须带 UA:
curl -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0" -s -o /dev/null -w "%{http_code}\n" https://example.com/
后台请求走 handleAdminProxy,在 SecurityGuard 之前就返回了,所以后台接口不受 UA 拦截影响。插件要做"给外部调用的 API",要么放行特定 UA,要么把入口挂到后台代理路径下,不要假设前台路由能随便 curl。
案例:后台设置页的完整 POST 闭环
function plugin_page_demo_settings($ctx): void
{
global $db;
$msg = '';
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
if (!Security::verifyCsrf()) {
$msg = '会话已失效,请刷新后重试';
} else {
$title = Security::post('title', '', 'str');
$score = Security::post('score', 0, 'int');
if ($title === '' || mb_strlen($title) > 60) {
$msg = '标题不能为空且不超过 60 字';
} elseif ($score < 0 || $score > 100) {
$msg = '分值必须在 0–100 之间';
} else {
Plugin::setConfig('title', $title, 'demo');
Plugin::setConfig('score', (string)$score, 'demo');
Extension::cacheForget('hot_list', 'plugin', 'demo');
$msg = '已保存';
}
}
}
echo '<div class="card"><h2>演示设置</h2>';
if ($msg !== '') echo '<p>' . Security::h($msg) . '</p>';
echo '<form method="post">' . Security::csrfField()
. '<input name="title" value="' . Security::h((string)Plugin::config('title', '', 'demo')) . '">'
. '<input name="score" type="number" value="' . (int)Plugin::config('score', 0, 'demo') . '">'
. '<button>保存</button></form></div>';
}
这个页面通过 ?action=plugin_page&pid=demo&page=settings 访问,文件放在 plugins/demo/pages/settings.php。它和 ?action=plugin&pid=demo(自动配置页)是两条路:前者完全自己控 UI,后者由框架按 PluginConfig 定义渲染表单。
语言包与国际化的落地
语言包就是"返回数组的 PHP 文件",一个语言一个文件。插件、主题各有自己的语言目录,互不干扰;缺哪个键就回退到默认文案,不会报错。
目录与格式
<?php
return array(
'plugin_name' => '演示插件',
'stats_title' => '统计看板',
'support_hint' => '当前站点共有 %s 本作品',
);
路径规则固定:插件 plugins/{id}/lang/{code}.php,主题 templates/{theme}/lang/{code}.php。{code} 用小写连字符格式(zh-cn、en-us),因为后台语言包管理会校验这个格式。默认语言是 zh-cn,非默认语言缺文件或缺键时自动回退到 zh-cn,再缺就用调用方给的 $default。
读取
Language::get('ui_ok', '确定');
Language::get('novel_count_hint', '共 %s 本', 128);
Language::pluginGet('demo', 'plugin_name', '演示插件');
Language::pluginGet('demo', 'support_hint', '', 1024);
Language::current();
返回值:Language::get('ui_ok') 取到"确定",Language::current() 返回 zh-cn。pluginGet() 的第一个参数是插件 id,它直接去该插件目录找文件,所以插件在自己页面里取文案不需要先"注册";registerPlugin($id) 用于把整包文案一次性载入内存,适合一个页面要取十几个键的场景。
语言包清单与可用性
| 方法 | 返回 | 用途 |
|---|---|---|
isLangAvailable($code) | bool | 当前主题或默认主题是否具备该语言 |
themeLanguages($theme) | 数组 | 扫描主题 lang/ 目录,列出已装语言 |
pluginLanguages($id) | 数组 | 扫描插件 lang/ 目录 |
getAllLanguages() | 数组 | 合并当前主题与默认主题的语言列表 |
jsStrings() | 数组 | 给前端 JS 用的固定键(确定 / 取消 / 关闭 / 菜单 / 语言 等) |
jsStrings() 的返回值通常由主题注入到 window.CMS_I18N 之类的位置,前端脚本取它来显示提示语。插件自己写的 JS 想拿文案,就在 head_end 里输出一段 window.DEMO_I18N = {...},值用 json_encode(Language::pluginGet(...)) 生成,别在 JS 里硬写中文。
语言包的上传与安装
| 方法 | 返回 |
|---|---|
installPluginPackage($id, $file, $code, $name='') | ['success','message'] |
installThemePackage($theme, $file, $code, $name='') | ['success','message'] |
uninstallPluginPackage($id, $code) / uninstallThemePackage($theme, $code) | ['success','message'] |
这几个方法是给后台"语言包管理"用的,会校验语言代码格式、只接受 .php 文件、写入语言元数据表并记录来源路径。插件一般不需要调用它们——除非你要在自己的设置页里做"一键安装语言包"。
案例:插件双语 + 模板取词
function plugin_init_demo($db): void
{
Language::registerPlugin('demo');
Hook::addAction('admin_dashboard_bottom', function () {
echo '<div class="card"><h2>' . Security::h(Language::pluginGet('demo', 'stats_title', '统计看板')) . '</h2>';
echo '<p>' . Security::h(Language::pluginGet('demo', 'support_hint', '共 %s 本', 128)) . '</p></div>';
}, 10, 'plugin:demo');
}
{t name="ui_ok" default="确定"}
{$demo_hint|t}
{t} 标签与 |t 修饰器读的是系统语言包(Language::get),不是插件包。插件自己的键要么在 PHP 侧取好再 assign,要么把 {t name="demo:key"} 这种写法放弃掉——框架不支持带命名空间的键。
写语言包的三条规矩:1. 键名用 小写_下划线,不要用中文键;2. 同一键在所有语言文件里必须都存在,缺了会静默回退中文,英文站会露出中文;3. %s 占位符的数量要与调用处一致,多传少传都不会报错,但文案会缺一块。
视图、模板与模板标签
视图层是 Smarty 的薄封装。View::render() 负责"输出整页"(含过滤器与标题后缀),View::fetch() 负责"拿回字符串"。插件渲染局部内容一律用 fetch(),不要用 render()——后者会直接 echo,还会重复走一遍 output_filter。
方法
| 方法 | 返回 | 说明 |
|---|---|---|
init($theme) | void | 框架启动时调用,建立 Smarty 实例与模板目录链 |
assign($key, $value) / assignArray($data) | void | 给模板变量赋值 |
render($template, $data=[]) | void | 渲染并输出;末尾走 output_filter 再追加站点标题后缀 |
fetch($template, $data=[]) | string | 只渲染,返回 HTML,不输出、不过滤 |
resolveTemplate($template) | string | 按目录链找出真实文件路径 |
addTemplateDir($dir) | void | 追加一个模板目录(会去重登记) |
getVars() / getTheme() / getSmarty() | 数组 / 字符串 / Smarty | 取当前变量、主题名、底层实例 |
模板覆盖链:谁先命中谁生效
| 顺序 | 目录 | 来源 |
|---|---|---|
| 1 | templates/{当前主题}/views/ | 默认注册 |
| 2 | templates/default/views/ | 默认注册,作为兜底 |
| 3 | 插件与第三方追加的目录 | view_template_dirs 过滤器 |
Hook::addFilter('view_template_dirs', function ($dirs) {
$dirs[] = ROOT_PATH . 'plugins/demo/views/';
return $dirs;
}, 10, 'plugin:demo');
这条链有两个后果,都要记住:主题可以用同名文件覆盖默认主题的模板(这是主题换肤的正规做法);插件模板必须用不易撞名的文件名(例如 demo_stats.tpl),否则一旦与主题里的 stats.tpl 同名,命中的是主题那个,而不是你的。
模板标签
| 标签 | 作用 |
|---|---|
{hook name="xxx"} | 执行同名动作钩子;可带参数,如 {hook name="library_item" item=$n},参数按位置传给回调 |
{sidebar slot="1"} | 输出该槽位的侧栏内容,slot 取 1–9 |
{ad name="header"} | 输出指定广告位,对应 ad_header 动作 |
{url route="read" id=$novel.id} | 按路由名生成站内地址,自动套 URL 格式配置 |
{qr content=$url assign="qr_uri"} | 生成二维码 data URI 并赋给变量 |
{t name="ui_ok" default="确定"} | 取系统语言键 |
{csrf_field} | 输出 CSRF 隐藏域 |
{captcha_field} | 输出验证码输入框与刷新控件 |
{pagination page=$page totalPages=$totalPages urlTpl="?page=@@PAGE@@"} | 输出分页条,参数为 page / totalPages / urlTpl / showJump |
{asset file="css/app.css"} | 站点公共资源 URL(带 BASE_URL),替代写死 /assets/... |
{theme_asset file="css/style.css"} | 当前主题资源 URL;加 theme="id" 可指定别的主题 |
修饰器
原生注册了两批:框架自带的 t(翻译)、truncate(截断)、date_format、number_format;以及为兼容补齐的字符串 / 数组 / 数值工具——ltrim rtrim trim substr strpos strtolower strtoupper ucfirst count empty sprintf cat json_encode max min。后一批的意义是不用开 $smarty->registerPlugin 也能在模板里做基本处理。
{$novel.title|truncate:20:"…"}
{$novel.created_at|date_format:"%Y-%m-%d"}
{$item.views|number_format}
{$item.tags|@json_encode}
{$item.title|substr:0:10}
案例:主题 include.php 的完整骨架
<?php
if (!defined('PLUGIN_BOOT')) exit;
View::addTemplateDir(ROOT_PATH . 'templates/demo/views');
Hook::addFilter('view_before_render', function ($vars, $template) {
$vars['theme_per_page'] = (int)Theme::config('reads_per_page', 12);
return $vars;
}, 10, 'theme:demo');
Hook::addFilter('view_template', function ($template) {
if ($template === 'index.tpl') {
return 'home.tpl';
}
return $template;
}, 10, 'theme:demo');
function theme_init($db): void
{
if (!is_dir(ROOT_PATH . 'data/theme/demo')) {
@mkdir(ROOT_PATH . 'data/theme/demo', 0755, true);
}
}
view_before_render 的 $vars 是即将 assign 给模板的变量数组,$template 是模板名;返回新数组即生效,返回 null 表示不改。view_template 用于改模板名(路由到不同模板),比在页面里判断主题名更干净。
插件渲染局部内容的标准写法:View::fetch('demo_stats.tpl', $data),模板文件放在 plugins/demo/views/ 并通过 view_template_dirs 登记。不要在插件里 new Smarty,也不要改 View::init 的目录链。
路由注册与页面入口
前台路由只有一条正规注册途径:router_routes 过滤器。除此之外的 URL 形态都由框架内置的三条默认路由接管,插件不要试图改 index.php 的分发逻辑。
注册自定义路由
Hook::addFilter('router_routes', function ($routes) {
$routes[] = array(
'pattern' => '#^demo/probe$#',
'handler' => 'DemoProbeController@index',
);
return $routes;
}, 10, 'plugin:demo');
require_once __DIR__ . '/controllers/DemoProbeController.php';
分发顺序:请求路径先做 preg_replace('/\.html$/', '') 去掉尾部 .html,然后先匹配注册路由,未命中再依次匹配默认路由,最后落到 404。pattern 必须带定界符(# 或 ~),整串匹配,不要只写前缀。注册 #^demo/probe$# 后访问 /demo/probe 与 /demo/probe.html 都命中同一控制器。
控制器类必须已经加载。框架 new $controller($db, $request) 之前不会自动 require 你的控制器文件——自动加载只扫描 app/core、app/models、app/controllers、app/services 四个目录,不扫 plugins/。所以要么在 main.php 里 require_once,要么把控制器放成 plugins/demo/controllers/XxxController.php 并在入口文件显式引入。
默认路由
| pattern | handler | 说明 |
|---|---|---|
#^plugin/(\w+)(?:/(\w+))?$# | PluginPageController@handle | 前台插件页统一入口 |
| 其余已配置的站点路由 | 各自的控制器 | 首页、书库、详情、阅读、榜单、作者、用户中心等 |
| 未命中 | NotFoundController@index | 渲染主题 404.tpl,http_response_code(404) |
案例:一个能跑通的自定义路由控制器
<?php
class DemoProbeController extends Controller
{
public function index($request = null): void
{
$this->db->query('SELECT 1');
$now = date('Y-m-d H:i:s');
header('Content-Type: application/json; charset=utf-8');
echo json_encode(array(
'ok' => true,
'now' => $now,
'path' => isset($_SERVER['REQUEST_URI']) ? $_SERVER['REQUEST_URI'] : '',
), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
}
}
控制器继承 Controller,构造由框架完成($db 与 $request 自动注入),实例内可直接用 $this->db。方法名就是 handler 里的 @ 后面那段。要输出 HTML 就自己 echo,要套主题布局就调 View::render()。
前台插件页:/plugin/{id}/{page}
这是最常用的入口,比自定义路由省事。访问 /plugin/demo/stats,框架会:
- 用
Security::validPluginId校验 id,不合法直接 404; - 用
Plugin::isEnabled校验启用状态,未启用返回 404; define('PLUGIN_PAGE_ACCESS', true),然后Hook::doAction('plugin_page_demo_stats', $this);require plugins/demo/pages/stats.php。
<?php
if (!defined('PLUGIN_PAGE_ACCESS')) exit;
$total = (int)$db->count('pc_gate_items');
?>
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>统计</title>
</head>
<body>
<h1>共 <?= $total ?> 条</h1>
</body>
</html>
页面里可直接用 $this(控制器实例)、$request、$db、$pluginId。页面必须自己输出完整 HTML——它不会被套进主题布局,也没有 header / footer 自动注入。想复用主题样式,就自己引 CSS,或者干脆在页面里 View::render('demo_stats.tpl', $data)。
注意这个边界:plugins/crawler/pages/crawl.php 入口处写了 if (!defined('ADMIN_BOOT')) exit;,它是后台专用页,前台访问 /plugin/crawler/crawl 返回 200 但响应体为空——HTTP 层面算成功,内容却是空的。这类页面不要放在能被前台路由命中的位置,或者把判断改成更明确的 404。
后台入口的四种形态
| URL | 行为 |
|---|---|
?action=plugin&pid=demo | plugins/demo/admin.php 存在则渲染它;不存在则看 PluginConfig::fields('demo'),非空时自动渲染配置表单(POST 经 CSRF 校验后 PluginConfig::save) |
?action=plugin_page&pid=demo&page=stats | plugins/demo/pages/stats.php |
经 admin_plugin_pages 注册的自定义 action | 如 ?action=crawl,键是 action 名,值是页面文件绝对路径 |
经 admin_menu 挂菜单 | 只是导航入口,落点仍是上面三种之一 |
Hook::addFilter('admin_plugin_pages', function ($pages) {
$base = __DIR__ . '/pages/';
$pages['demo_stats'] = $base . 'stats.php';
return $pages;
}, 10, 'plugin:demo');
注意键名会成为 URL 里的 action:访问 ?action=demo_stats 即渲染该文件。后台页面不需要 PLUGIN_PAGE_ACCESS,但要做登录态与 CSRF 校验——后台代理层已经处理了登录态,POST 仍需 Security::verifyCsrf()。
路由 vs 插件页怎么选:要返回 JSON、要接受路径参数(如 /demo/probe/128)、要和主题无关——用 router_routes。要输出一个短页面、且希望 Plugin::isEnabled 自动帮你挡掉停用状态——用前台插件页。
后台界面扩展
后台扩展分四类:加菜单、加页面、给已有列表加列、给已有编辑页加字段。前两类是自己造界面,后两类是往别人的界面里插东西——这两类的收益最高,代码也最少。
加菜单:两种写法
Extension::menu(array(
array('action' => 'plugin_page?page=stats', 'label' => '统计看板', 'icon' => 'fa-chart-line', 'group' => '内容管理'),
array('action' => 'plugin_page?page=rules', 'label' => '规则设置', 'icon' => 'fa-sliders', 'group' => '内容管理'),
));
action 是不带 pid 的查询串——框架会自动补上当前插件 id;group 匹配现有分组标题,匹配不到归入"扩展功能";icon 用 Font Awesome 类名。
Hook::addFilter('admin_menu', function ($groups) {
$link = function (string $page): string {
return 'plugin_page?pid=demo&page=' . $page;
};
$groups[] = array(
'title' => '演示功能',
'items' => array(
array($link('stats'), '统计看板', 'fa-chart-line'),
array($link('rules'), '规则设置', 'fa-sliders'),
),
);
return $groups;
}, 10, 'plugin:demo');
items 里每一项都是三元素数字索引数组:[链接, 文本, 图标],不是关联数组。写成 array('url' => ...) 不会报错,但菜单项会渲染成空白。
改页面标题
Hook::addFilter('admin_page_title', function ($title, $action) {
if ($action === 'demo_stats') {
return '统计看板';
}
return $title;
}, 10, 'plugin:demo');
第二个参数是当前 action。返回空串会让标题区变成空白,所以不要 return null——返回原值。
给已有列表加列:PluginTable
PluginTable::addColumn('admin.novels', array(
'key' => 'demo_score',
'label' => '评分',
'width' => '70px',
'align' => 'center',
'render' => function ($row) {
$v = isset($row['rating']) ? (float)$row['rating'] : 0;
return $v > 0 ? '<span class="badge badge-green">' . number_format($v, 1) . ' 分</span>' : '-';
},
));
| 字段 | 必填 | 说明 |
|---|---|---|
key | 是 | 列表内唯一;重复注册时先注册者生效 |
label | 是 | 列头文本,可用 t_admin() 做多语言 |
render | 是 | function ($row),返回任意 HTML;$row 是该行完整数组 |
width / align | 否 | 写到 <th> 的内联样式 |
class | 否 | 加到 <td> |
页面侧由框架调用三个方法:renderHead($key) 输出 <th>、renderCells($key, $row) 输出 <td data-col="key">、count($key) 给空数据行的 colspan 追加列数。已接入 22 个 key:
admin.novels admin.chapters admin.chapters_all
admin.orders admin.users admin.authors
admin.vip_review admin.withdraw admin.ads
admin.announcements admin.categories admin.author_applications
admin.volumes admin.sign_logs admin.sales_stats
admin.vip_stats admin.diy_blocks admin.security_logs
admin.plugins admin.cron admin.language_admin
admin.language_front admin.language_theme
效果:注册 probe_score 与 probe_avg 两列后,小说列表 20 行每行都输出真实计算值(5.4 分 / 1,196),空态 colspan 自动加 2。回调抛异常时该单元格输出为空并写入 error_log,不影响其他行。
给已有编辑页加字段:PluginForm
PluginForm::addField('novel_edit', array(
'name' => 'demo_badge',
'label' => '角标文案',
'type' => 'text',
'default' => '',
'hint' => '显示在封面右上角',
));
PluginForm::addField('novel_edit', array(
'name' => 'demo_tags',
'label' => '标签',
'type' => 'checkbox_group',
'options' => array('hot' => '热门', 'mystery' => '悬疑'),
));
| type | 提交值形态 |
|---|---|
text(默认)/ textarea / date / hidden | 字符串 |
number | 数值字符串 |
switch | 1 / 0 |
select / radio | 选项值 |
checkbox | 1 / 空 |
checkbox_group / multiselect | JSON 数组字符串 |
提交值统一走 $_POST['ext'][name],落到 plugin_data 的 entity_type / data_key / data_value 三个字段,按实体 id 回填。页面侧成对调用:
<?= PluginForm::render('novel_edit', 'novel', (int)$novel['id']) ?>
PluginForm::save('novel_edit', 'novel', (int)$novel['id']);
render() 放在表单按钮之前,save() 放在保存分支内。已接入 novel_edit、chapter_edit、user_edit、category_edit、ad_edit、announcement_edit 六个页面。九种类型都能落库,重开页面时按原值回填。
行操作与编辑页插入位
Hook::addAction('admin_orders_row_actions', function ($row, $extra = 0) {
$id = (int)($row['id'] ?? 0);
if ($id <= 0) return;
$url = admin_url('order_flag', array('id' => $id, 'csrf' => Security::csrfToken()));
echo '<a class="btn btn-xs" href="' . Security::h($url) . '">标记</a>';
}, 10, 'plugin:demo');
admin_{tab}_row_actions 覆盖 novels / chapters / categories / authors / users / orders / ads / announcements / vip_review / withdraw / volumes。chapters 与 volumes 会多传 $novelId,所以回调第二个参数写成带默认值的最稳。
编辑页的插入位是 admin_novel_edit_extra($novel)、admin_chapter_edit_extra($chapter, $novelId)、admin_user_edit_extra($user),对应的保存后钩子是 admin_*_edit_saved。要"加字段 + 自己存",用这一组;只想存值不想管 UI,用 PluginForm。
前端资源注入:Ui
Ui::registerFront();
Ui::registerAdmin();
Ui::frontCss();
Ui::frontJs();
Ui::adminCss();
Ui::adminJs();
registerFront() 把 frontCss/frontJs 挂到 head_end 与 body_end,registerAdmin() 挂到 admin_head 与 admin_footer,输出 css/ui.css 与 js/uikit.js。插件需要自己的一套 UI 组件时,不要往这两个文件里塞——在自己的 head_end 回调里输出自己的 CSS,URI 用 Extension::url('plugin', 'demo') 拼,避免写死域名。
案例:一个插件的后台三件套
function plugin_init_demo($db): void
{
Extension::menu(array(
array('action' => 'plugin_page?page=stats', 'label' => '统计看板', 'icon' => 'fa-chart-line', 'group' => '内容管理'),
));
PluginTable::addColumn('admin.novels', array(
'key' => 'demo_score',
'label' => '演示分',
'width' => '70px',
'render' => function ($row) {
return '<span class="badge">' . (int)($row['rating'] ?? 0) . '</span>';
},
));
Hook::addFilter('admin_page_title', function ($title, $action) {
return $action === 'demo_stats' ? '统计看板' : $title;
}, 10, 'plugin:demo');
Hook::addAction('admin_head', function () {
echo '<style>.demo-badge{font-weight:600}</style>';
}, 10, 'plugin:demo');
}
后台扩展的三条铁律:1. 所有输出都要 Security::h(),包括从库里读出来的字段(数据可能被注入过);2. 所有 POST 都要 Security::verifyCsrf(),后台代理不替你校验;3. 不要在 admin_head 里做查询——它每个后台页都会执行,会拖慢整个后台。
网络请求与内容工具
采集、外链校验、第三方 API 都走 Network,不要直接 file_get_contents——它没有超时、没有 SSRF 防护、不会带合适的 UA。
Network
| 方法 | 返回 | 说明 |
|---|---|---|
get($url, $opts=[]) | 数组 | GET |
post($url, $data=null, $opts=[]) | 数组 | POST,$data 可为数组或字符串 |
json($url, $opts=[]) | ?数组 | 期望 JSON;解不出返回 null |
download($url, $savePath, $opts=[]) | 数组 | 落盘,返回 ok / path / bytes / headers / error |
request($url, $opts=[]) | 数组 | 底层统一入口,$opts['method'] 指定方法 |
isSafeUrl($url, $allowHosts=[]) | 数组 | ['ok'=>bool, 'error'=>string],拒绝 localhost、内网 IP、非 http(s) |
前五个方法的返回结构一致:['ok'=>bool, 'http'=>int, 'body'=>string, 'headers'=>array, 'error'=>string, 'json'=>?array]。失败时 ok=false 且 error 有文案,不要只看 http 码——DNS 失败、超时都会让 http 为 0。
isSafeUrl 返回的是数组不是布尔!直接写 if (Network::isSafeUrl($url)) 永远为真(非空数组)。正确写法:$chk = Network::isSafeUrl($url); if (!$chk['ok']) { … }。这是个静默失效的坑。
UA 工具
Network::defaultUaPool();
Network::randomBrowserUa();
Network::clientUa();
Network::fillUaTemplate('Mozilla/5.0 ({os}) {engine} Chrome/{ver}');
站点对"无浏览器 UA"的请求会返回 403(SecurityGuard 那层,见 16 章)。写采集器时优先用 Network::randomBrowserUa() 从池里取,而不是写死一个 Chrome 字符串——池里的版本会跟着更新。
案例:抓一页、清洗、落库
function demo_fetch_page(string $url): ?string
{
$chk = Network::isSafeUrl($url);
if (!$chk['ok']) {
Logger::plugin('demo', 'url rejected', array('url' => $url, 'why' => $chk['error']));
return null;
}
$res = Network::get($url, array(
'ua' => Network::randomBrowserUa(),
'timeout' => 15,
));
if (!$res['ok'] || $res['http'] !== 200) {
Logger::plugin('demo', 'fetch failed', array(
'url' => $url,
'http' => $res['http'],
'error' => $res['error'],
));
return null;
}
return CommonService::htmlToPlainText($res['body']);
}
CommonService:内容处理
| 方法 | 说明 |
|---|---|
isSpider() | 无参,读当前 UA 判断是否蜘蛛 |
smartWordCount($text) | 中英混排字数;smartWordCount('中文测试 hello world') 得 6 |
htmlToPlainText($html) | 去标签、去多余空白 |
cleanPlainText($text) | 纯文本清洗(控制字符、全角空格、连续空行) |
formatNumberShort($n) | 万/亿缩写;12345 输出 1.235万 |
sanitizeRichText($html) | 富文本白名单:p/br/b/strong/i/em/u/h2/h3/blockquote/ul/ol/li,p 只留 text-indent:2em,去掉 on* 与 javascript: |
formatTimeAgo($time) | "3 分钟前"这类相对时间 |
recordVisit($novelId) | 记一次阅读量 |
pointName() / rechargeRate() / currencyName() / currencySymbol() / toCny($amount) | 站点货币与积分口径,读设置项 |
写章节正文、简介、公告这类用户可编辑的富文本,入库前必须过 sanitizeRichText()。白名单外的东西一律丢,不然后台编辑框会带进 <script> 或 onerror,前台一渲染就中招。
$content = CommonService::sanitizeRichText((string)$_POST['content']);
$db->update('chapters', array(
'title' => Security::post('title'),
'content' => $content,
'words' => CommonService::smartWordCount(CommonService::htmlToPlainText($content)),
), array('id' => (int)$chapterId));
顺序很重要:先 sanitizeRichText 再 smartWordCount。如果先数字数再清洗,被剥掉的标签和样式会被算进字数里,站内统计会偏大。
支付网关与定时任务
这两块都是"接口型扩展":框架定好抽象类或触发点,插件实现具体逻辑。它们的共同点是没有 UI——只在业务流程里被调用。
支付网关
| 成员 | 类型 | 说明 |
|---|---|---|
getId() | 抽象 | 网关唯一标识,如 epay |
getName() | 抽象 | 显示名 |
isEnabled() | 抽象 | 是否可用,通常读自己的配置 |
createOrder(array $params) | 抽象 | 下单,返回数组(通常是跳转地址或二维码内容) |
verifyNotify(array $data) | 抽象 | 校验回调签名,返回 bool |
parseNotify(array $data) | 抽象 | 解析回调,返回业务字段 |
getIcon() | 可选 | 默认 fa-credit-card |
getConfigFields() | 可选 | 后台配置项定义,默认空 |
getSupportedMethods() | 可选 | 默认返回支付宝 + 微信两项 |
PaymentGatewayRegistry::load();
PaymentGatewayRegistry::register($gateway);
PaymentGatewayRegistry::get('epay');
PaymentGatewayRegistry::all();
PaymentGatewayRegistry::default();
load() 只跑一次,内部执行 payment_gateways 过滤器并收走所有 PaymentGateway 实例;all() 只返回 isEnabled() 为真的网关;default() 取第一个可用网关。注册网关的正规方式是在 main.php 挂过滤器,而不是直接调 register()——后者会绕过 load 的一次性保证,在重复加载时容易重复注册。
案例:一个最小可用的网关骨架
<?php
class DemoGateway extends PaymentGateway
{
public function getId(): string { return 'demo'; }
public function getName(): string { return '演示支付'; }
public function isEnabled(): bool
{
return (string)Plugin::config('enabled', '0', 'demo') === '1';
}
public function createOrder(array $params): array
{
$orderNo = (string)($params['order_no'] ?? '');
if ($orderNo === '') {
return array('ok' => false, 'msg' => '订单号缺失');
}
return array(
'ok' => true,
'type' => 'url',
'value' => 'https://pay.example.com/checkout?no=' . urlencode($orderNo),
);
}
public function verifyNotify(array $data): bool
{
$sign = (string)($data['sign'] ?? '');
$raw = (string)($data['order_no'] ?? '') . (string)($data['amount'] ?? '');
return $sign !== '' && hash_equals(hash_hmac('sha256', $raw, (string)Plugin::config('secret', '', 'demo')), $sign);
}
public function parseNotify(array $data): array
{
return array(
'order_no' => (string)($data['order_no'] ?? ''),
'amount' => (float)($data['amount'] ?? 0),
'paid' => ((string)($data['status'] ?? '') === 'SUCCESS'),
);
}
}
Hook::addFilter('payment_gateways', function ($list) {
$list[] = new DemoGateway();
return $list;
}, 10, 'plugin:demo');
回调安全三条:签名比较必须用 hash_equals(防时序攻击);金额要和自己库里的订单金额对比,不能只信回调给的数;回调处理必须幂等——同一个订单重复通知不能重复加余额。
定时任务
Cron::tasks();
$cron = new Cron();
$cron->runAll();
$cron->warmCache();
$cron->cleanup();
| 成员 | 类型 | 说明 |
|---|---|---|
tasks() | 静态 | 返回内置任务元数据(warm_cache 每 4 分钟、clear_expired 每小时),供后台展示 |
runAll() | 实例 | 依次执行 warmCache() 与 cleanup() |
warmCache() | 实例 | 预热首页数据 |
cleanup() | 实例 | 清理过期登录记录(login_attempts 表不存在时直接返回) |
插件不要往 Cron::tasks() 里塞任务——它是静态数组,改不了。正确做法是挂 cron_run 动作,由系统定时脚本每轮触发:
Hook::addAction('cron_run', function () {
$last = (int)Extension::cacheGet('last_scan', 0, 'plugin', 'demo');
if (time() - $last < 600) {
return;
}
Extension::cacheSet('last_scan', time(), 0, 'plugin', 'demo');
try {
$rows = PluginDB::all('items', array('status' => 0));
Logger::plugin('demo', 'demo scan', array('pending' => count($rows)));
} catch (\Throwable $e) {
Logger::plugin('demo', 'demo scan failed', array('err' => $e->getMessage()));
}
}, 10, 'plugin:demo');
用缓存存"上次执行时间"是标准做法:cron_run 可能被更频繁地触发(系统里有多个定时入口),自己控频比依赖外部调度可靠。cacheSet 传 0 表示永不过期,正好当持久标记用。
定时任务三条:1. 必须自己控频,不要假设"每小时只跑一次";2. 必须 try/catch 并写日志,一条异常不该让整轮 cron 挂掉;3. 不要在 cron 里 echo 大段输出——CLI 输出会进邮件或被截断,只写日志。
状态码与错误处理
站点对"错误"有两套处理:可预期的(资源不存在、没权限、请求太频繁)走状态码 + 主题 404 页;不可预期的(语法错误、数据库断连、未捕获异常)走 ErrorHandler + 通用错误页。插件要分清自己遇到的是哪一种。
状态码对照
| 码 | 什么时候发 | 由谁发 |
|---|---|---|
| 200 | 正常返回;pc_gate 的 page200 模式也用 200 返回拦截页 | 框架 / 插件 |
| 304 | 静态资源未变更 | Bootstrap |
| 403 | 无浏览器 UA 的前台请求;pc_gate 拦截 PC 访问;非管理员访问后台 | SecurityGuard / 插件 |
| 404 | 插件不存在或未启用、路由未命中、合法 id 校验失败、文件缺失 | PluginPageController / NotFoundController |
| 405 | 接口只允许 POST 却收到 GET | 插件自己实现 |
| 429 | 请求频率超限(限流文件在 data/ 下,.json.php 后缀自保护) | SecurityGuard / 插件 |
| 500 | 数据库连接失败、未捕获异常、模板渲染失败 | Database / ErrorHandler / View |
| 503 | 站点维护中(由配置或插件接管) | 插件 |
三个典型响应:访问 /plugin/pc_gate/xxx(插件停用时)返回 404;访问 /plugin/notexist/xxx 同样 404;首页正常返回 200。这两条 404 由路由层直接返回,不经过主题的 404.tpl,所以响应体极短——拿它判断"是不是走错层了",比猜日志更快。
404 的唯一入口
根目录 404.php 是全局 404 落点:未安装时输出裸 404;已安装时把 URI 改写成 /__not_found__ 再 require index.php,由 NotFoundController 渲染主题 404.tpl 并设置 http_response_code(404)。nginx 侧配 error_page 404 =404 /404.php;,静态资源缺失、被 deny 的目录都走同一套页面。
所以插件不要自己写 404 HTML。要返回 404,只需把状态码和页面交给现有链路:
public function show($id = 0): void
{
$row = PluginDB::findById('items', (int)$id);
if (!$row) {
http_response_code(404);
View::render('404.tpl', array('message' => '内容不存在'));
return;
}
View::render('demo_show.tpl', array('row' => $row));
}
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
http_response_code(405);
header('Allow: POST');
echo json_encode(array('ok' => false, 'msg' => 'method not allowed'));
return;
}
$key = 'demo_api_' . md5((string)($_SERVER['REMOTE_ADDR'] ?? ''));
$hit = (int)Extension::cacheGet($key, 0, 'plugin', 'demo');
if ($hit >= 30) {
http_response_code(429);
header('Retry-After: 60');
echo json_encode(array('ok' => false, 'msg' => 'too many requests'));
return;
}
Extension::cacheSet($key, $hit + 1, 60, 'plugin', 'demo');
用缓存做限流是"零环境依赖"的做法:键按 IP 哈希,60 秒窗口,超 30 次就 429。Retry-After 头告诉客户端多久后重试,别省略。
错误处理与调试开关
| 机制 | 行为 |
|---|---|
ErrorHandler::register() | 注册错误、异常、关闭回调;未捕获异常与致命错误统一输出 500 错误页并写日志 |
DEBUG 常量 | config/config.php 里为 true 时展开错误详情;false 时关闭 display_errors,只留日志 |
Database 连接失败 | 直接 http_response_code(500) 并输出提示,不抛白屏 |
View 渲染失败 | 内部 renderErrorPage() 输出带详情的错误页(该方法是 private,插件不能直接调) |
Hook 回调抛异常 | 被捕获、写 error_log('[hook:...]')、链继续执行——一个插件的 bug 不会拖垮整页 |
PluginTable / PluginForm 回调异常 | 该单元格 / 该字段输出为空,不影响其他部分 |
调试纪律:开发时可以在 config/config.php 里临时开 DEBUG=true,上线前必须改回 false。插件代码里不允许出现 var_dump、print_r、echo $e->getMessage() 这类直接打错误详情的写法——异常信息里常带绝对路径、SQL 片段、甚至配置值,等于把内部结构送给访客。
案例:一个统一的失败出口
function demo_json_fail(int $code, string $msg): void
{
http_response_code($code);
header('Content-Type: application/json; charset=utf-8');
echo json_encode(array('ok' => false, 'msg' => $msg), JSON_UNESCAPED_UNICODE);
Logger::plugin('demo', 'demo api fail', array('code' => $code, 'msg' => $msg));
}
if (!Security::verifyCsrf()) {
demo_json_fail(403, '会话已失效');
return;
}
把"状态码 + JSON + 日志"收进一个函数,比在每个分支里手写三行更不容易漏。注意日志里写的是给运维看的信息,返回给客户端的是给用户看的信息,两者不要混用同一句话。
开发红线
这一章是"必须遵守,没有例外"的清单。前九条是这套系统当前强制的规范,第十条是交付前自查。
1. 注释:一个文件只留一条
全站口径是每个脚本文件顶部只保留一条页面功能说明,其余注释一律删除。这里的"脚本"包括 PHP、CSS、JS、模板。
| 文件类型 | 保留 | 必须删除 |
|---|---|---|
| PHP | 文件顶部 1 条,≤40 字,说明这个文件干什么 | 类注释、方法注释、行内注释、分节注释、被注释掉的旧代码 |
| CSS | 无 | 分区标题、属性说明、被注释的样式 |
| JS | 无 | 函数说明、调试日志、被注释的代码 |
| 模板(tpl / html) | 无 | <!-- --> 注释、分节标记 |
<?php
/** 插件主入口:注册后台菜单与列表列 */
if (!defined('PLUGIN_BOOT')) exit;
function plugin_init_demo($db): void
{
Extension::menu(array(...));
}
硬性上限:一条注释不超过 40 字,不带版本号、作者、日期、修改记录——这些属于 git,不属于源码。TODO / FIXME / XXX 一律不允许留在提交里。
2. 不写硬编码
| 不要这样 | 要这样 |
|---|---|
'本站'、'确定' 直接写在页面里 | Language::get('ui_ok','确定') / Language::pluginGet('demo','key') |
'https://www.xxx.com/...' | url('read', array('id'=>$id)) / admin_url('plugin', ...) / Extension::url('plugin','demo') |
'D:\wwwroot\...' 或 '/var/www/...' | ROOT_PATH . 'plugins/demo/...' |
| 把每页条数、开关、阈值写死在代码里 | Plugin::config('per_page','20','demo') / Theme::config('reads_per_page',12) |
| 表名手拼字符串 | $db->table('novels') / PluginDB::* |
3. data/ 目录不许乱写
data/ 在站点根内,是"能被 Web 直接命中"的目录。规则只有一条:系统生成、格式固定的文件才允许带执行后缀并加防泄漏头;外部可控内容一律不用执行后缀。
| 内容 | 允许的后缀 | 原因 |
|---|---|---|
| 缓存 | md5(key).cache.php | 首行 <?php exit; ?>,被访问时立即退出,输出空 |
| 限流计数 | .json.php | 同上 |
| PHP 错误日志 | php_errors.log.php | 同上 |
| 业务日志 | {channel}.{hex}.log | 文件名随机不可枚举,内容不含敏感信息(见 12 章) |
| 章节正文 | .txt | 内容外部可控,绝不能挂执行后缀 |
| 上传的图片 | 白名单后缀 | 落盘前过 Security::verifyImageUpload |
4. 不改框架核心,除非它有缺陷
app/core 是公共层,插件直接改它等于让所有插件都依赖你的版本。发现框架能力不够时,有两条路:先考虑用现有钩子 / 过滤器组合出来;确实缺能力,才补到 app/core 并同步更新这份手册。补的时候不加注释、不改变现有方法的签名与语义——加就加新方法。
5. 不动 vendor/ 与 assets/js/jsqr.js、assets/fontawesome
第三方库保持原样,升级时能整包替换。需要定制就在自己的目录里包一层,不要改库文件。
6. 日志只走 Logger
不自建日志文件、不指定日志路径、不写固定文件名、不把日志存成 .php、不记录密码与 token(掩码只认键名,拼在正文里就漏了)。详见 12 章。
7. 插件缓存必须带单元前缀
用 Extension::cacheGet/Set/Remember/Forget/Flush,不要直接 Cache::set('my_key')——后者会和系统、其他插件撞键,且卸载时清不干净。
8. 安全四件事
输出必转义(Security::h);POST 必验 CSRF(Security::verifyCsrf);上传必过校验(verifyImageUpload / verifyZipUpload);SQL 必参数化(? 占位,或 $db->from()->where())。这四条任何一条破了,其余做得再好都没意义。
9. 卸载必须清干净
| 要清的 | 怎么清 |
|---|---|
| 配置 | Plugin::purgeConfig($id) 或 plugin_uninstall_{id} 里删 plugin_data |
| 表 | Plugin::purgeTables($id) 或逐张 dropTable |
| 缓存 | Extension::cacheFlush('plugin', $id) |
| 钩子 | 框架自动 removeOwner,不用手写 |
| 日志 | Logger::clearPlugin($id),只清 data/logs/plugins/{id}/ |
10. 命名
插件 id、主题 id 一律 ^[a-z0-9_]+$,全小写,不用连字符与大写;表名用短名(items、logs),实际表名由框架拼成 En_{pluginId}_items;函数名加插件前缀(plugin_init_demo、demo_task_run),避免与系统函数或别的插件重名。
上线检查与排错
必须文件
| 类型 | 必须 | 说明 |
|---|---|---|
| 插件 | plugin.xml | 清单,至少含 name 与 version |
| 插件 | main.php | 入口,被 require 时完成钩子注册;首行做 PLUGIN_BOOT 判断 |
| 主题 | theme.xml | 清单,必须含 name 与 version;type 缺省按 pc 处理 |
| 主题 | include.php | 入口,注册模板目录、钩子、theme_init |
| 主题 | views/*.tpl | 至少覆盖首页、列表、详情、阅读四类,否则页面会渲染失败 |
目录结构
plugins/demo/
├── plugin.xml 清单
├── main.php 入口(必须)
├── admin.php 后台主设置页(可选)
├── controllers/ 自定义路由控制器
├── pages/ 前台 / 后台页面
├── views/ 模板
├── lib/ 业务类
├── assets/ 静态资源(css / js / img)
├── lang/ 语言包(zh-cn.php / en-us.php)
└── data/ 插件私有数据(不放进站点 data/)
templates/demo/
├── theme.xml
├── include.php
├── config.php 主题设置字段定义(可选,但建议有)
├── views/ 页面模板
├── assets/ 静态资源
└── lang/ 语言包
插件私有数据放 plugins/demo/data/(自己判 is_dir 再 mkdir),不要往站点 data/ 里建子目录——那会让"清理 data 等于清全站"的运维习惯变成事故。PluginTable 与 PluginForm 的数据都在数据库里,不需要额外目录。
交付前自查
| # | 检查项 | 判定 |
|---|---|---|
| 1 | 清单能被解析 | Extension::info('plugin','demo') 返回非空数组 |
| 2 | 入口有防直接访问 | 首行 if (!defined('PLUGIN_BOOT')) exit; |
| 3 | 每个文件只有一条顶部注释 | ≤40 字,无类注释 / 方法注释 / 行内注释 |
| 4 | 无硬编码文案与地址 | 全部走语言包与 url() / Extension::url() |
| 5 | 语法全过 | php -l 无错;模板能 View::fetch() 出内容 |
| 6 | 停用后不留残留 | 停用后钩子失效、页面 404,缓存被清 |
| 7 | 卸载后干净 | 配置、表、缓存、日志都清掉 |
| 8 | 所有 POST 有 CSRF | Security::verifyCsrf() 在写操作前 |
| 9 | 所有输出有转义 | 用户可控内容过 Security::h() |
| 10 | SQL 无拼接 | 手写 SQL 用 ? 占位 + $db->table() |
| 11 | 日志走 Logger | 无自建 .log 文件、无固定文件名 |
| 12 | 后台页有登录态 | 页面不直接暴露给未登录访客 |
出问题先看哪里
| 症状 | 先查 |
|---|---|
| 后台扩展列表里看不到 | 目录名与 id 是否一致;plugin.xml / theme.xml 能否被 simplexml_load_file() 解析 |
| 启用后前台毫无变化 | main.php 是否被 require;钩子名是否拼错;回调是否在 plugin_init_{id} 里注册(08 章) |
| 页面 500 且没有报错信息 | 先 php -l;再打开 DEBUG 看完整错误页;模板路径是否在目录链里(18 章) |
| 列表页空白或分页错乱 | 分页返回键混用:PluginDB::paginate 是 rows/total/pages,QueryBuilder::paginate 是 list/total/totalPages(10 章) |
| 查不到数据、报表不存在 | 表前缀三条规则:系统表 from()、插件表 PluginDB、手写 SQL 用 $db->table()(10 章) |
| 提交表单但数据没变 | verifyCsrf() 没过就静默返回;表单里是否渲染了 csrf_field(16 章) |
| 邮件发不出去 | SMTP 六项设置是否齐全;465 走 ssl、587 走 tls,端口与加密方式要匹配(13 章) |
| 日志写了但读不到 | 插件日志是否走 Logger::plugin('{id}')、{id} 是否与目录名一致;系统通道写不进是正常的(12 章) |
| 二维码扫不出来 | 内容是否超过 500 字符;解码只能在前端做,PHP 侧没有解码器(15 章) |
| 切主题后样式错乱 | 模板目录链与缓存:先 Cache::flush(),再核对 views/ 是否齐全(11、18 章) |
先在 12 章的日志里找线索,再回这张表定位是哪一层的问题——绝大多数现象都能归到"注册位置不对、名字拼错、前缀漏了、CSRF 没过"这四类。
最容易踩的十个坑
| 坑 | 现象 | 对策 |
|---|---|---|
| 手写 SQL 用裸表名 | Table 'db.xxx' doesn't exist | 用 $db->table() |
| 插件表当成系统表查 | 同样报不存在 | PluginDB::* 或 $db->from('demo_items') |
钩子里调 Plugin::view() | 静默返回空字符串 | 先 View::addTemplateDir(),再用 View::fetch() |
| 控制器没 require | Class not found | 在 main.php 里 require_once |
| 无 UA 的 curl | 前台一律 403 | 带浏览器 UA |
isSafeUrl 当布尔用 | 永远为真 | 取 ['ok'] |
QueryBuilder::where 写成三参数 | 参数错位、条件失效 | where('`x` = ?', array($v)) |
PluginDB::paginate 与 QueryBuilder::paginate 返回键混用 | 列表空白或分页错乱 | 前者 rows/total/pages,后者 list/total/totalPages |
| 菜单 items 写成关联数组 | 菜单项空白 | array($url, $label, $icon) |
| 模板文件名撞名 | 渲染出主题的同名模板 | 插件模板加前缀 demo_stats.tpl |
全篇只写框架当前真实提供的能力,不写理想设计。动手前建议先读 plugins/crawler(后台页 + 路由 + cron 的完整样本)与 plugins/pc_gate(钩子 + 配置 + 二维码 + 日志的完整样本),这两个是最贴近真实用法的参考实现。遇到手册没覆盖的细节,以这两个目录里的代码为准。
公共 API 速查
给扩展用的公共面只有三层:app/core/functions.php 里的全局函数、框架类里的公开方法、页面渲染前已经赋好的变量。三层之外都算内部实现——private / protected 成员、Bootstrap 的内部流程、View::renderErrorPage() 这种只给自己用的方法,插件和主题都不要碰。
一、全局函数
全部定义在 functions.php,每条都包在 if (!function_exists()) 里。插件与主题的任何文件都能直接调,不需要 require。
| 族 | 函数 | 要点 |
|---|---|---|
| 表名 | tb($t) tb_raw($t) | 前者返回带反引号的全名,后者裸名;手写 SQL 用前者 |
| 输入 | inp($k, $d, $type) g() p() filter_value($v, $type) | inp 一次取 GET+POST;$type 取 int / float / bool / str / raw / array |
| 转义 | e($s) h($s) | 输出进 HTML 一律 h();两者都基于 htmlspecialchars |
| 站点 URL | url($route, $params) url_full() | url 返回站内路径(不含 BASE_URL),url_full 带域名前缀 |
| 页面 URL | novelUrl readUrl userUrl libraryUrl rankUrl authorsUrl | 按 URL 模板反解出链接,参数与后台"URL 格式"设置保持同步 |
| 前缀 | urlPrefix($name, $default) | 读 URL 设置里的路径前缀,拼自定义页面地址用 |
| 资源 | asset($rel) theme_asset($rel, $theme) plugin_asset($id, $rel) admin_asset($rel) | 四个都自带 BASE_URL;theme_asset 缺省当前主题,plugin_asset 对不存在的 id 返回空串 |
| 后台 | admin_dir() admin_url($action, $params) admin_query() t_admin($key, $default, ...$args) | 后台入口由代理映射,不要手拼 /admin/ |
| 设备 | device_type($ua) is_mobile($ua) is_pc($ua) | 返回 pc / mobile;传 $ua 可测任意 UA 串 |
| 文本 | excerpt($s, $len, $etc) cms_minor($ver) brand_title($html) | 按全角字截断;取版本前两位;给 <title> 追版权后缀 |
| 二维码 | qr_code_library() qr_code_color() qr_code_png() qr_code_data_uri() qr_code_save() | 只在后端生成,内容 ≤500 字符;解码在前端 jsqr |
| 扩展 | enovelcms_plugins_run($file) | 按启用顺序执行一个插件入口文件,插件内部批量调用用 |
二、模板标签
注册在 View::init(),主题模板与插件模板通用。
| 标签 | 参数 | 输出 |
|---|---|---|
{hook name="head_end"} | name | 执行同名动作,插件在这里挂样式与脚本 |
{sidebar slot=3} | slot 1–9 | 渲染该侧栏位已登记的组件 |
{ad name="home_top"} | name | 后台配置的广告位 HTML |
{url route="novel" id=12} | route + 任意参数 | 与 url() 同源的链接 |
{qr content="..." assign="q"} | content / assign | PNG data URI,写了 assign 则存入变量 |
{t name="ui_ok" default="确定"} | name / default | 当前语言包文案 |
{asset file='css/app.css'} | file | 站点公共资源 URL,带 BASE_URL |
{theme_asset file='css/style.css' theme="default"} | file / theme | 主题资源 URL,theme 缺省用当前主题 |
{csrf_field} {captcha_field} | 无 | 隐藏域 / 验证码块 |
{pagination page=2 totalPages=9 urlTpl="?page=@@PAGE@@"} | page / totalPages / urlTpl / showJump | 分页条 HTML |
修饰器共 20 个:t truncate date_format number_format ltrim rtrim trim substr strpos strtolower strtoupper ucfirst count empty sprintf cat json_encode max min。
三、框架类
| 类 | 用途 | 常用公开入口 | 章节 |
|---|---|---|---|
Database | 连接与执行 | table from query insert update delete fetchAll fetchOne count | 10 |
QueryBuilder | 链式条件 | where select orderBy groupBy limit get first count paginate | 10 |
PluginDB | 插件表 | insert find findById all update delete count paginate search | 10 |
ChapterShard | 章节分片 | 按 SHARD_SIZE 定位分表的读写入口 | 10 |
Hook | 动作与过滤器 | addAction addFilter doAction applyFilters suspendOwner removeOwner | 5、6 |
Cache | 四驱动缓存 | get set delete flush remember | 11 |
Logger | 文件日志 | plugin theme readPlugin readTheme clearPlugin extensions | 12 |
Security | 转义、CSRF、上传 | h csrfToken verifyCsrf hashPassword input verifyImageUpload safeFilename | 16 |
Language | 系统与扩展语言包 | get pluginGet registerPlugin current jsStrings | 17 |
Theme | 主题注册与配置 | activePc activeMobile scanAll enable typeOf supports readManifest | 9 |
Plugin | 插件注册与配置 | isEnabled enabledIds all config setConfig createTable view | 8 |
Extension | 统一扩展内核 | load info conf menu setting sidebar table field cacheGet cacheSet | 7 |
View | Smarty 封装 | init assign assignArray fetch render addTemplateDir | 18 |
Network | HTTP 客户端 | get post request download isSafeUrl | 21 |
MailService | SMTP 发信 | new MailService -> send sendVerifyCode | 13 |
CommonService | 内容与爬虫判断 | isSpider smartWordCount formatNumberShort sanitizeRichText | 21 |
Cron | 定时任务 | tasks runAll warmCache cleanup | 22 |
Ui | 前后台资源注入 | registerFront registerAdmin | 20 |
PaymentGateway | 支付接口契约 | getId getName isEnabled createOrder verifyNotify parseNotify | 22 |
PaymentGatewayRegistry | 网关注册表 | load register get enabled | 22 |
ErrorHandler | 统一错误页 | register | 23 |
另有 PluginConfig、PluginForm、PluginTable、ThemeConfig、AdminLanguage 五个组件类,分别服务配置表单、表单字段注入、列表渲染、主题配置与后台语言包;它们由框架在对应页面里调用,插件一般不直接 new。
四、页面级变量
这些变量不是函数,是渲染前已经放在作用域里的值,直接用就行。
主题模板(.tpl)
| 变量 | 含义 |
|---|---|
$siteName $siteKeywords $siteDesc $siteLogo | 站点基础信息与 logo 地址 |
$themeUrl | 当前主题根 URL(BASE_URL . '/templates/' . 主题) |
$csrf_token | 当前会话 CSRF token,配合 {csrf_field} |
$seo | title / keywords / description |
$siteLangs $currentLang | 可用语言列表与当前语言 |
$user_id $username $user $userGold | 访客身份与余额,未登录时 $user_id 为 0 |
$html_lang $js_lang | 语言代码与前端文案包(JSON 字符串) |
$captcha_enabled | 验证码开关 |
$point_name $currency_name $currency_symbol $exchange_rate | 积分名、货币名与符号、充值折算率 |
插件前台页(plugins/{id}/pages/{page}.php)
| 变量 | 含义 |
|---|---|
$db | Database 实例 |
$request | Request 实例,取参数与用户 |
$pluginId | 当前插件 id |
$siteName | 站点名 |
$themeUrl | 当前主题根 URL |
$pluginUrl | 本插件根 URL,等于 Extension::url('plugin', $id) |
PLUGIN_PAGE_ACCESS | 常量,页面被直接访问时不存在,用它挡直接请求 |
渲染这个页面时框架已经 Extension::begin('plugin', $id) 过,所以页面里 Extension::conf('page_title', '默认值') 读的就是本插件配置;页面结束自动 end()。
后台页(admin/pages/*.php、插件 admin.php)
| 变量 / 函数 | 含义 |
|---|---|
$db $action $pid | 数据库、当前 action、插件 id(插件页才有) |
$loggedIn $flash $adminEntry | 登录态、一次性提示、后台入口 URL |
admin_pagination($page, $totalPages, $query) | 后台分页条 HTML |
admin_flash_redirect($msg, $action, $extra) | 写 flash 并跳回后台页 |
五、案例
插件前台页:不吃主题模板,自己输出完整 HTML
<?php
if (!defined('PLUGIN_PAGE_ACCESS')) { http_response_code(404); exit; }
?>
<!DOCTYPE html>
<html lang="<?php echo h(Language::current()); ?>">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title><?php echo h(Extension::conf('page_title', '插件统计')); ?> · <?php echo h($siteName); ?></title>
<link rel="stylesheet" href="<?php echo h($themeUrl); ?>/css/style.css">
<link rel="stylesheet" href="<?php echo h(plugin_asset($pluginId, 'css/stat.css')); ?>">
</head>
<body>
<main>
<h1><?php echo h(Extension::conf('page_title', '插件统计')); ?></h1>
<p><?php echo Language::get('stat_total', '总计'); ?>:<?php echo (int)$db->from('demo_hits')->count(); ?></p>
<p><a href="<?php echo h(BASE_URL); ?>/"><?php echo Language::get('back_home', '返回首页'); ?></a></p>
</main>
</body>
</html>
三件事同时成立:PLUGIN_PAGE_ACCESS 挡掉直接访问;$themeUrl 与 plugin_asset() 让样式跟着站点根走;Extension::conf() 直接读到本插件配置,不用再传 id。
主题模板:资源地址不写死
<link rel="stylesheet" href="{asset file='fontawesome/css/all.min.css'}">
<link rel="stylesheet" href="{theme_asset file='css/style.css'}">
<script src="{asset file='js/jsqr.js'}"></script>
{asset} 指向站点 /assets/,{theme_asset} 指向当前主题目录。站点装在子目录、或者走了二级路径时,这两个标签会自动带上正确前缀;写死 /assets/... 就会 404。
边界几条:
1. 不 new Bootstrap、不手动 require 核心类文件——自动加载只扫 app/core、models、controllers、services 四个目录,插件目录不在其中。
2. 不调 private / protected 方法(例如 View::renderErrorPage()),也不改 View 的静态属性,赋值一律走 assign() / assignArray()。
3. 不读 $_GET / $_POST 原始数组,用 inp() / g() / p() 或 Security::input(),类型与默认值一次给清。
4. 不手拼后台地址。后台物理目录由代理映射,一条 admin_url('plugin', array('pid' => 'demo')) 就够了。
5. 不假设主题一定叫 default:PC 与手机端可以挂不同主题,要用 theme_asset() 或 $themeUrl,不要写死目录名。
嵌入点总表
全站一共 84 处触发点、74 个名称,分成动作(doAction,只通知,无返回值)与过滤器(applyFilters,必须返回被改过的值)两类。下面按前台、数据层、后台、输出链分组,名称与参数都取自源码,参数名以触发处实际传入的为准。
一、前台动作
| 名称 | 参数 | 触发位置 | 用途 |
|---|---|---|---|
core_before_controller | $controller, $action | Router::dispatch 进控制器前 | 全局前置:鉴权、埋点、限流 |
core_after_controller | $controller, $action | 控制器返回后 | 全局后置:收尾、统计 |
user_login_success | $user, $_POST | UserController 登录成功 | 登录奖励、同步第三方 |
user_register_success | $user, $_POST | 注册成功 | 欢迎信、赠送积分 |
user_profile_saved | $userId, $_POST | 资料保存后 | 同步昵称、头像 |
author_novel_published | $novelId, $userId, $_POST | 作者发布作品 | 推送、审核队列 |
author_chapter_published | $novelId, $chapterId, $_POST | 作者发布章节 | 更新提醒、生成静态页 |
ad_{name} | $name | {ad name="xxx"} 渲染时 | 自定义广告位内容 |
sidebar_{slot} | $slot(1–9) | {sidebar slot=n} | 按槽位挂侧栏组件 |
sidebar | $slot | 同上,槽位动作之后 | 统一处理所有槽位 |
plugin_page_{id}_{page} | $controller | 插件前台页 require 前 | 页面级前置逻辑 |
{hook name="xxx"} | $name + 模板参数按位置传 | View::smartyHook | 模板里执行任意动作 |
二、前台过滤器
| 名称 | 参数 | 触发位置 | 用途 |
|---|---|---|---|
router_routes | $routes | Router 建表时 | 注册自定义路由 |
library_filters | $filters, $request | LibraryController | 改书库筛选条件集合 |
library_where | ['where','params'], $filters | NovelModel | 往书库查询追 SQL 条件 |
library_order_sql | $orderSql, $orderBy, $filters | 同上 | 换排序语句 |
library_order_options | $orders | LibraryController | 加排序选项 |
library_order_labels | $labels | 同上 | 排序选项的显示名 |
library_status_labels | $labels | 同上 | 状态筛选项名 |
library_vip_labels | $labels | 同上 | VIP 筛选项名 |
rank_types | $valid | RankController | 加榜单类型 |
rank_type_labels | $labels | 同上 | 榜单类型显示名 |
rank_order_sql | $order, $type, $timeRange | NovelModel | 换榜单排序字段 |
diy_block_where | ['where','params'], $block | NovelService | DIY 区块查询条件 |
diy_block_order_sql | $orderBy, $block | 同上 | DIY 区块排序 |
diy_block_fields | $fields, $block | 同上 | DIY 区块额外字段 |
captcha_verify | null, $input | Security::verifyCaptcha | 接管验证码校验,返回 true/false |
captcha_render_html | $defaultHtml, $name, $placeholder | Security::captchaHtml | 换验证码渲染 |
view_template_dirs | $dirs | View::init | 加模板查找目录 |
view_before_render | $vars, $template | View::render | 渲染前改全部变量 |
view_template | $template, $vars | 同上 | 换模板文件 |
output_filter | $html, $template | View::render 输出前 | 改最终 HTML |
payment_gateways | $gateways | PaymentGatewayRegistry::load | 注册支付网关 |
三、数据层
模型层统一触发,第三个参数是表名,用来判断该不该管这次写入。
| 名称 | 类型 | 参数 | 用途 |
|---|---|---|---|
db_before_insert | 过滤器 | $data, $table | 入库前改字段 |
db_after_insert | 动作 | $id, $data, $table | 入库后连带处理 |
db_before_update | 过滤器 | $data, $where, $table | 更新前改字段 |
db_after_update | 动作 | $affected, $where, $table | 更新后同步 |
db_after_delete | 动作 | $affected, $where, $table | 删除后清理 |
form_saved_{key} | 动作 | $entityType, $entityId, $post | 注入的表单保存后回调 |
章节正文走分表,ChapterModel 在分片切换时会对同一个钩子再触发一次,$table 随之变化;只认主表的实现要判一下表名。
四、后台动作
| 名称 | 参数 | 输出位置 | 用途 |
|---|---|---|---|
admin_head | 无 | 后台 </head> 前 | 注入后台样式与脚本 |
admin_footer | 无 | 后台页尾 | 注入后台脚本 |
admin_login_after_form | $action | 登录表单后 | 加登录项 |
admin_login_footer | $action | 登录页尾 | 登录页补充内容 |
admin_sidebar_top / admin_sidebar_bottom | 无 | 侧栏上下 | 侧栏附加块 |
admin_dashboard_top / admin_dashboard_stats_after / admin_dashboard_bottom | 无 | 仪表盘 | 看板卡片、统计块 |
admin_content_top / admin_content_bottom | $action | 内容区上下 | 全后台页通用提示条 |
admin_settings_after | 无 | 设置页表单后 | 加设置项 |
admin_novel_edit_extra | $novel | 作品编辑表单内 | 加字段 |
admin_novel_edit_saved | $id, $_POST | 作品保存后 | 连带保存 |
admin_chapter_edit_extra | $chapter, $novelId | 章节编辑表单内 | 加字段 |
admin_chapter_edit_saved | $chapterId, $novelId, $_POST | 章节保存后 | 连带处理 |
admin_user_edit_extra | $user | 用户编辑表单内 | 加字段 |
admin_user_edit_saved | $userId, $_POST | 用户保存后 | 连带处理 |
admin_ads_row_actions | $ad | 广告列表行 | 行内按钮 |
admin_announcements_row_actions | $a | 公告列表行 | 行内按钮 |
admin_authors_row_actions | $a | 作者列表行 | 行内按钮 |
admin_categories_row_actions | $cc | 分类列表行 | 行内按钮 |
admin_chapters_row_actions | $c, $novelId | 章节列表行 | 行内按钮 |
admin_novels_row_actions | $n | 作品列表行 | 行内按钮 |
admin_orders_row_actions | $o | 订单列表行 | 行内按钮 |
admin_users_row_actions | $u | 用户列表行 | 行内按钮 |
admin_vip_review_row_actions | $n | VIP 审核行 | 行内按钮 |
admin_volumes_row_actions | $v, $novelId | 分卷列表行 | 行内按钮 |
admin_withdraw_row_actions | $row | 提现列表行 | 行内按钮 |
五、后台过滤器
| 名称 | 参数 | 触发位置 | 用途 |
|---|---|---|---|
admin_menu | $menuGroups | admin/includes/sidebar.php | 往侧栏菜单加分组或条目 |
admin_plugin_pages | $pages | admin/index.php | 注册 ?action=xxx 映射到插件文件 |
admin_page_title | $title, $action | 后台标题 | 改页面标题 |
admin_novel_save_data | $data | 作品保存前 | 入库前改字段 |
diy_status_options / diy_time_options / diy_order_options | $options | DIY 区块配置页 | 加筛选项 |
六、案例
给作品列表行加一个按钮
Hook::addAction('admin_novels_row_actions', function ($n) {
$url = admin_url('plugin', array('pid' => 'demo', 'nid' => (int)$n['id']));
echo '<a class="btn btn-sm" href="' . htmlspecialchars($url) . '">同步</a>';
}, 10, 'plugin:demo');
行操作钩子在每个表格行的操作列里输出,三个后台列表(作品、章节、分卷)还会多传一个小说 id,做跨表操作时用得上。
给书库加一条查询条件
Hook::addFilter('library_where', function ($cond, $filters) {
if (($filters['views_min'] ?? '') === '') return $cond;
$cond['where'] .= ' AND `views` >= ?';
$cond['params'][] = (int)$filters['views_min'];
return $cond;
}, 10, 'plugin:demo');
$cond 是 ['where' => '', 'params' => []]:追加 SQL 片段用 $cond['where'],绑定值按顺序塞进 $cond['params'],两者数量必须对齐。改了筛选界面的选项名,要在 library_filters 里同时补上,否则用户根本选不到这个条件。
页面数据地图
主题开发要天天用的那张表:一个页面对应哪个控制器方法、渲染哪个 .tpl、模板里能拿到哪些变量、这些变量里的列表从哪个方法出来。这一章按页面顺序铺开。
一、变量从哪来
控制器里写 $this->view('library.tpl', $data),第二个参数的每个键就是模板里的同名变量。在这之前,Controller::init() 已经塞了一批全局变量,任何页面都能直接引用。
| 变量 | 内容 |
|---|---|
$siteName / $siteKeywords / $siteDesc | 后台站点设置 |
$siteLogo | 优先 data/uploads/theme_logos/{主题}.png,没有则用后台 site_logo |
$themeUrl | BASE_URL/templates/{当前主题},拼 CSS / 图片用 |
$user_id / $username / $user / $userGold | 当前登录用户,未登录时 $user 为 null |
$csrf_token | 表单隐藏域的值,也可以直接用 {csrf_field} |
$seo | 数组 title / keywords / description,控制器会按页面覆盖 |
$siteLangs / $currentLang | 可选语言列表与当前语言 |
$js_lang / $html_lang | 渲染前注入:JS 语言包 JSON、<html lang> 值 |
渲染顺序是:全局变量 → 页面 $data 合并 → view_before_render 过滤 → 补 js_lang / html_lang → view_template 换模板 → 输出过 output_filter。合并是覆盖式的,页面 $data 的键优先。
二、页面 → 控制器 → 模板
| 页面 | 入口 | 控制器方法 | 模板文件 |
|---|---|---|---|
| 首页 | 站点根 | HomeController::index | home.tpl |
| 书库 | library 前缀,可带分类与筛选段 | LibraryController::index | library.tpl |
| 排行榜 | rank 前缀 + 类型 | RankController::index | rank.tpl |
| 作品详情 | novel 前缀 + 作品 id(可带章节页码) | NovelController::detail | novel_detail.tpl |
| 阅读页 | read 前缀 + 作品 id + 章节 id | ReadController::index | read.tpl |
| 搜索 | search 前缀 | SearchController::index | search.tpl |
| 作者列表 | authors | AuthorController::index | authors.tpl |
| 作者主页 | author 前缀 + 用户 id | AuthorController::detail | author_detail.tpl |
| 用户中心 | user/{action} | UserController::handle | user/index.tpl、user/login.tpl、user/bookshelf.tpl 等 |
| 作者中心 | authorcenter/{action} | AuthorCenterController::handle | author/works.tpl、author/chapter_list.tpl 等 |
| 支付回跳 | pay/return | PayController::handle | user/pay_return.tpl |
| 404 | 未匹配任何路由 | NotFoundController::index | 404.tpl |
| 插件前台页 | plugin/{id}/{page} | PluginPageController::handle | plugins/{id}/pages/{page}.php |
404.tpl 只认一个 $message;lock.tpl 同理,作者中心权限不足时用它。语言切换(lang)与 API(api/{name})不渲染模板。
三、各页面变量清单
首页 home.tpl
| 变量 | 结构 |
|---|---|
$announcements | 公告数组:title / content / link / created_at |
$categories | 分类树,键是分类 id,每项含 children |
$heroSlider / $heroTable / $heroRank | 三个主视觉区块,每项含 id / name / title / num / novels |
$sections | 其余区块,通常 {foreach $sections as $b} 逐块输出 $b.novels |
$rankBlocks / $randomBlocks | 名字为 rank_* 与 random_novels 的区块 |
$blocks | 全部区块的原始列表 |
书库 library.tpl
| 变量 | 结构 |
|---|---|
$list / $novels | 当前页作品数组,SELECT * 直出表字段 |
$total / $page / $perPage / $totalPages | 总数、当前页、每页条数、总页数 |
$categories | 分类树 |
$filters | category_id / order_by / vip_filter / status / keyword / min_words / max_words |
$currentCategory | 当前分类 id,整数 |
$orderOptions / $orderLabels | 排序键数组(如 update)与对应显示名 |
$statusLabels / $vipLabels | all / ongoing / finished 与 all / vip / free 的显示名 |
排行榜 rank.tpl:$type(当前类型)、$list 与 $novels(同一份榜单数组)、$types(全部类型键)、$typeLabels(类型 → 显示名)。getRank 会给每条补 category_name。
详情 novel_detail.tpl
| 变量 | 结构 |
|---|---|
$novel | 作品行:title / author / cover / description / status / views / favorites / total_words / chapter_count / category_id / is_vip |
$author | 作者行:id / pen_name / signature / avatar,不是签约作者时为空数组 |
$volumes / $chapters | 分卷列表与章节平铺列表 |
$chaptersByVolume | 按分卷分组:{卷id: {volume: ..., chapters: [...]}},只含当前页章节 |
$chapterPage / $chapterTotalPages / $chapterTotal / $chapterPerPage | 章节分页,每页 100 |
$related | 相关推荐(读 related_novels 区块,没有则随机 6 本) |
$inBookshelf | 布尔,当前用户是否已收藏 |
阅读 read.tpl
| 变量 | 结构 |
|---|---|
$novel / $chapter | 作品行与章节行 |
$content | 已转成 HTML 的正文;无权阅读时是前 N 字预览 |
$perm | allowed / need_pay / preview / preview_words / auto_on / auto_purchased / auto_purchase_failed |
$prev / $next | 上/下一章行,没有时为 null |
$purchaseError | 仅在 POST 购买失败时 assign |
搜索 search.tpl:$list / $total / $keyword / $page / $totalPages,关键词为空时列表为空。
作者页:authors.tpl 拿到 $list / $total / $page / $totalPages,外加全局 $pageUrlTpl(把 @@PAGE@@ 替换成页码);author_detail.tpl 拿到 $author / $novels / $page / $totalPages / $totalWorks / $totalWords / $totalViews,同样带 $pageUrlTpl。
用户中心:user/index.tpl 拿 $user / $bookshelf / $history(两个计数);其余页面按用途给单个对象或错误串,例如 user/profile.tpl 拿 $user、user/recharge.tpl 拿 $error。作者中心:author/works.tpl 拿 $works 与 $novelResult,author/novel_add.tpl 拿 $categories,其余编辑页拿对应的 $novel / $chapter / $volume。
四、取数方法
模板里不能调模型,取数发生在控制器或主题的 include.php 里。可用的方法按用途分四族。
| 要什么 | 方法 | 返回 |
|---|---|---|
| 分类平铺 | CategoryModel::getAllCategories() | id / name / parent_id / sort,静态缓存 |
| 分类树 | CategoryModel::getCategoryTree()、getTree() | 一级分类为键,子分类在 children |
| 含子分类的 id 集合 | CategoryModel::getCategoryAndChildIds($id)、getChildIds($parentId) | 整数数组,含自身 |
| 书库列表 | NovelModel::getLibrary($filters, $page, $perPage) | list / total / page / perPage / totalPages |
| 榜单 | NovelModel::getRank($type, $limit, $timeRange) | 数组,带 category_name |
| 搜索 | NovelModel::search($keyword, $page, $perPage) | 同上结构 |
| 随机推荐 | NovelModel::getRandom($limit) | 数组 |
| 按 id 批量取 | NovelModel::getByIds($ids) | 数组 |
| 作者作品 | NovelModel::getByAuthor($userId, $page, $perPage) | 列表分页结构 |
| VIP 畅销 | NovelModel::getVipBestsellers($limit) | 数组,带 vip_sales_amount |
| 整页数据 | NovelService::getHomeData()、getLibraryData()、getNovelDetail($id)、getReadData($novelId, $chapterId, $userId) | 直接喂给 $this->view() |
| 区块数据 | NovelService::getBlockNovelsByName($name)、getHomeBlocks()、getRelatedNovels() | 作品数组 |
两个缓存点要知道:书库前 10 页走 Cache(键含 filters 与页码,300 秒),榜单走 novel_rank_{type}_{limit}_{timeRange}(600 秒)。改了数据看不到变化时,是命中这里。
五、状态、排序、榜单类型
| 字段 | 取值 | SQL 条件 |
|---|---|---|
status | 0 连载 / 1 完本 | status = 0 / status = 1 |
is_vip | 0 免费 / 1 VIP | is_vip = 0 / is_vip = 1 |
书库 order_by 六个值:update(COALESCE(last_chapter_time, created_at) DESC, id DESC)、new(created_at DESC, id DESC)、id(id DESC)、views、favorites、words。榜单五个类型:views、favorites、words、new(按更新时间)、chapters(按章节数);$timeRange 传 week 时只取近七天有更新的书,其余传 all。
六、自定义榜单
后台「自定义榜单」就是 DIY 区块:一个名字加一组条件,前台按名字取。创建在后台 ?action=diy_blocks,字段是这些。
| 字段 | 含义 |
|---|---|
name | 标识符,字母数字下划线,全站唯一,创建后只读 |
title | 显示标题,留空则用标识符 |
num | 条数,1–100 |
category_id | 多选分类,存成 0(不限)或逗号串 |
status | all / ongoing / finished |
time_range | all / today / week / month / year,按入库时间 |
order_by | views / new / update / favorites / chapters / words / vip_sales_amount / vip_sales_count / random / custom |
min_words / max_words | 字数区间,0 不限 |
custom_ids | 仅 custom 用:逗号分隔的作品 id,按列出顺序排最前,其余按 id 倒序补足 |
cache_time | 缓存秒数,0 不缓存;结果 JSON 存在区块的 data 字段 |
读取就一句:NovelService::getBlockNovelsByName('week_finished'),返回作品数组,每条含 id / title / author / category_id / category_name / cover / description / status / views / total_words / favorites / is_vip / last_chapter_title / last_chapter_time / total_chapters / vip_sales_amount / vip_sales_count。名字不存在时返回空数组,不抛错。
首页自动认几个约定名:hero_slider、hero_table、hero_rank 进三个主视觉,rank_views / rank_favorites / rank_words 进 rankBlocks,random_novels 进 randomBlocks,其余全部进 sections;related_novels 不在首页出现,专供详情页相关推荐。
案例:在主题里把自定义榜单挂到首页
Hook::addFilter('view_before_render', function ($vars, $tpl) {
if ($tpl === 'home.tpl') {
$vars['weekFinished'] = (new NovelService())->getBlockNovelsByName('week_finished');
}
return $vars;
}, 10, 'theme:default');
$tpl 是模板文件名,按它判断只在需要的页面取数;返回值必须是数组,少 return 会让整页变量变空。
案例:模板里渲染这个榜单
{if $weekFinished}
<section class="home-card">
<h3>本周完本</h3>
<ul class="book-list">
{foreach $weekFinished as $n}
<li>
<a href="{url route="novel" id=$n.id}">{$n.title}</a>
<span class="meta">{$n.author} · {$n.category_name}</span>
</li>
{/foreach}
</ul>
</section>
{/if}
案例:模板里读筛选现状与选项名
<div class="sort-bar">
{foreach $orderOptions as $o}
<span class="sort{if $filters.order_by == $o} on{/if}">{$orderLabels[$o]}</span>
{/foreach}
<span class="sort{if $filters.status == 'ongoing'} on{/if}">{$statusLabels.ongoing}</span>
<span class="sort{if $filters.status == 'finished'} on{/if}">{$statusLabels.finished}</span>
</div>
选项键与显示名都从控制器来,主题不要把它们写死——插件通过 library_order_options、library_status_labels 加的选项会自动出现在这里。
案例:在 include.php 里直接取数
$svc = new NovelService();
$rank = NovelModel::getRank('chapters', 10, 'all');
$lib = NovelModel::getLibrary(array(
'category_id' => 3,
'order_by' => 'words',
'status' => 'finished',
'vip_filter' => 'free',
), 1, 20);
getLibrary 的 $filters 允许只给几个键,缺的按默认处理;category_id 会自动带上所有子分类。
七、边界
模板不能调用模型和函数,只能读变量、用 12 个内置标签;要新数据,在 include.php 里挂 view_before_render 注入,别在 .tpl 里塞 PHP。页面 $data 会覆盖同名全局变量,所以别把键起成 user、seo、themeUrl 这些名字。想换整个页面的模板文件用 view_template 过滤,想改最终 HTML 用 output_filter,两者的语义与参数在 06 章。