EnovelCms 3.0 开发手册PLUGIN / THEME
PHP 8.0+
ENOVELCMS 3.0  /  EXTENSION MANUAL  /  2026-11-15

插件与主题开发手册
EnovelCms开发者入门必看

写给要给 EnovelCms 写插件、写主题的人。公共函数、数据层、缓存、日志、邮件、设备判断、二维码、安全、语言包、视图、路由、后台界面、支付、定时任务,逐项给出方法签名、真实语义和可以直接复制运行的案例。读完你能独立做出一个能装、能配、能卸的插件,或一套能上线的主题。

全篇只描述框架现在真实提供的能力,不写设想中的 API。所有案例都是同一套写法:PHP 8.0 起可直接运行,不依赖 Composer、PECL 扩展或 Redis 这类可选服务。

28章节
101可复制案例
12类扩展能力
8.0–8.4PHP 版本支持
01

开始之前

这套框架是原生 PHP 的 MVC,没有 Composer 自动加载、没有容器、没有事件总线框架。所有扩展能力都收敛在 app/core 下的几个静态类里,插件与主题通过"清单文件 + 入口文件 + 嵌入点"接入。理解这一点,后面所有 API 的形状就都顺了。

适用对象

  • 要做一个独立功能插件(采集、支付、过滤、拦截、友情链接等),不改动核心代码。
  • 要做一套前台主题(PC 固定宽或移动端),复用框架的数据与模板标签。
  • 要给已有插件补后台设置页、列表列、编辑表单字段。

框架边界

  • 只使用框架已有的类与函数。不引入新的第三方依赖,不假设服务器装了 Redis、Memcached、Composer。
  • 不改 config/config.php 里的常量名与数据库结构,插件自己的表自成体系。
  • 插件与主题代码不写进 app/,不修改框架文件;框架确实缺能力时,补到 app/core 并按第 24 章的红线执行,不要在自己的插件里绕一套私有实现。

运行环境

项目要求说明
PHP8.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。

02

目录结构与必须文件

插件放 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}/。落盘路径、文件名与轮转由框架决定,插件不参与。

03

清单文件

清单是扩展对框架的"自我介绍",也是后台判断能否安装的唯一依据。解析走 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插件占用的侧栏槽位,供主题渲染
plugins/pc_gate/plugin.xml
<?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 主题硬挂到手机端。

templates/default/theme.xml
<?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 的写法)

theme.xml 片段 · settings 与 menus
<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 节点语法
<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() 返回三段结构:

checkRequirements 的返回形状
array(
  'ok'       => false,
  'errors'   => array('依赖 plugin:epay 未安装,请先安装'),
  'warnings' => array('依赖 plugin:word_filter 已安装但未启用'),
)

errors 非空即拒绝安装;warnings 只提示,不阻断。清单改动后务必 Extension::flushInfo('plugin', 'pc_gate') 清掉缓存,否则后台读到的还是旧版本号。

04

生命周期与加载时序

框架每个请求都走同一条启动流水线。插件与主题能做什么、不能做什么,取决于它在这条流水线上的站位:注册钩子要早,输出内容要晚,改路由要在路由之前。

REQUEST PIPELINE 1 2 3 4 5 6 7 常量与函数ROOT_PATH / helpers 缓存与数据库Cache::init / setDb 安全守卫SecurityGuard 视图与语言View::init / Language 主题入口include.php 插件入口main.php 路由分发Router 扩展从第 5 步开始接入,到第 6 步注册完毕; 第 7 步之后的所有钩子都已可拦截。 第 1–4 步属于框架自身:这一阶段没有插件代码参与, 所以插件无法影响常量、数据库连接与安全策略。 CORE_BEFORE_CONTROLLER → CONTROLLER → CORE_AFTER_CONTROLLER / OUTPUT_FILTER 在 render 末尾

Bootstrap 启动顺序

  1. defineConstants定义 ROOT_PATH、PRIVATE_PATH、BASE_URL、ADMIN_URL、DB_PREFIX、DEBUG 相关常量。
  2. functions.php载入全局函数,此后 g()、t_admin()、url()、qr_code_png() 等随时可用。
  3. ErrorHandler / session / Cache::init注册异常与错误处理、开 session、按配置初始化缓存驱动(yac 不可用则退化成文件缓存)。
  4. Database + Model::setDb建立 PDO 连接(异常模式、关闭模拟预处理),并注入到 Model / 各扩展内核。
  5. SecurityGuard + 安全响应头UA 黑名单、IP 拦截、限流、恶意路径拦截;命中即直接输出拦截页并结束。
  6. View::init + Language::init + Ui::registerFront确定当前主题、装配模板目录、载入语言包、注册前台资源钩子。
  7. Theme::loadInclude按 active_theme 与 mobile_theme 依次 require 主题 include.php,在 Extension::begin('theme', id) 上下文中执行。
  8. Plugin::init按注册表顺序 require 已启用插件的 main.php,逐个 Extension::begin / end,加载后注册插件语言包。
  9. 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 的情况下处理写操作

插件入口的最小骨架

plugins/demo/main.php
<?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} 包装后语义更清楚,也便于单独调试。

05

钩子(动作)

全站一共 84 处触发点、74 个名称,逐个的参数与位置列在 27 章嵌入点总表;这一章只讲语义与纪律。

动作是"告知型"嵌入点:框架在某个时刻喊一声,谁注册了就执行谁,执行完继续走自己的流程。它不回传值,也不改变框架的行为——除非回调里显式返回信号或直接终结请求。

addAction / doAction 签名
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__),比对是严格相等,返回同字面量的字符串也算命中。

案例:注册、优先级、清理

plugins/demo/main.php · 三档优先级与 owner 归属
<?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() 终止请求

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) 最稳。

06

过滤器

名称、参数与触发位置的全量索引见 27 章嵌入点总表;这一章讲写法:返回什么、什么时候会被跳过、改错会怎样。

过滤器是"改写型"嵌入点:框架把一个值交给你,你返回新值,框架用新值继续。这是唯一能改变框架行为的正规途径——改路由、改 SQL 片段、改输出 HTML、加后台菜单,全靠它。

addFilter / applyFilters 签名
Hook::addFilter(string $hook, callable $callback, int $priority = 10, ?string $owner = null): void
Hook::applyFilters(string $hook, $value, ...$args)

回调的第一个参数永远是当前值,后面的参数是框架附带的上下文。链条是串联的:A 的返回值是 B 的输入。返回 null 不会覆盖原值,返回 SIGNAL_STOP 会以"此刻已累积的值"结束整条链。

案例:注册自定义路由

router_routes · 唯一官方路由注册途径
<?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 等价。

案例:改书库查询条件

library_where · 返回 where 片段与绑定参数
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

library_order_sql / rank_order_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() 这类函数调用是允许的,写子查询会被剥掉。

案例:写入前改数据

db_before_insert / db_before_update
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);返回的数组整体替换待写入数据,未返回则原样写入。这里适合做"补默认值、做字段映射",不适合做权限判断(此时已经在写库路径上)。

案例:输出末尾注入

output_filter · 全站 HTML 出口
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 或纯文本响应后面粘一段注释。

案例:后台加菜单组

admin_menu · 追加菜单分组
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_verifynull, $input → bool接管验证码校验(返回非 null 即由插件裁决)
captcha_render_html$html, $name, $placeholder → HTML替换验证码控件

性能与安全

  • 过滤器在热路径上(library_where 每次列表查询都跑),回调里不要查库、不要发网络请求。
  • 拼接 SQL 片段只允许固定字符与 ?;任何用户输入都必须走 params。
  • 输出改写类过滤器要考虑响应不是 HTML 的情况(JSON 接口、附件下载)。
  • 同一条链上多个插件改写同一值时,优先级决定覆盖顺序;需要"最终生效"就把优先级设大。
07

扩展内核 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)boolrequire 入口并调用 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)路径 / URLROOT_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 返回默认值,调用方不需要额外判断。

声明:菜单、设置项、侧栏、列表列、表单字段

main.php 中的声明式用法
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 时执行一次;写在某个钩子回调里只会在该回调触发时才登记,后台页面可能已经渲染完了。

08

插件 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)boolplugins/{id}/admin.php 是否存在

isEnabled() 只看启用标记:启用返回 true,停用返回 false。而 hasAdminPage() 判断的是 admin.php 是否存在,与启用状态无关——所以一个插件停用后 hasAdminPage() 仍可能为 true,只是用户进不去它的功能页。

配置读写

配置存 plugin_data 表,键 entity_type='config'
Plugin::setConfig('notice', '本站启用 CDN', 'demo');

$notice = Plugin::config('notice', '默认值', 'demo');

$notice2 = Plugin::config('notice', '默认值');

Plugin::flushConfigCache('demo');

省略第三个参数时取当前加载的插件,因此在 main.php 里可以简写;在页面、控制器、CLI 脚本里必须显式传 id,否则会读到空。flushConfigCache() 用于配置改动后清掉进程内缓存(同一请求里先写后读的场景)。

建表:自动加插件前缀

createTable / addColumn / dropColumn
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 已被清空,函数找不到模板目录。这个错误不会抛异常,只会静默返回空,表现为"后台多了一块空白"。排查时优先怀疑这一条。

案例:完整的插件数据闭环

plugins/demo/main.php · 安装建表 + 运行时读写
<?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);没有定义时框架只更新版本号,不动数据。

09

主题 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。

主题配置

templates/default/config.php · 字段定义
<?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

templates/demo/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 的主题不要加移动端媒体查询——那会和手机主题互相打架。

10

数据层

四层结构: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 / getColumnsbool / 数组建表维护
addColumn / modifyColumn / dropColumnbool列变更,第二参数为列名,第三为完整定义
addIndex($t, $name, $columns) / dropIndexbool普通索引;唯一索引请直接写列定义里的 UNIQUE
beginTransaction / commit / rollBackbool事务
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 表。

11

缓存 Cache

四个驱动,一个接口。是否启用由 config/config.php 里的 CACHE_ENABLE 决定,驱动由 CACHE_DRIVER 决定,默认 TTL 由 CACHE_TTL 决定(默认 300 秒)。驱动不可用时自动回退文件驱动,不会抛异常。

驱动可用条件适用
file始终可用单机、无扩展环境,最稳
memcachedextension_loaded('memcached')多进程共享
redisextension_loaded('redis')多机共享、需主动失效
yac扩展已装且 yac.enable 为真(CLI 还需 yac.enable_cli=1)进程内共享内存,最快

方法

Cache 与 Extension 缓存的分工
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,键会爆炸且很难失效——这类数据直接查库,通常也够快。

12

日志 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,不落盘、不建目录。

插件与主题日志

按扩展 id 分子目录
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 就是"最新在上"。

敏感字段自动掩码

context 里这些键会被替换成 ***
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}.log200知道完整路径才能读;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 分目录的原因。

13

邮件 MailService

邮件走 PHPMailer + SMTP,配置全部来自 settings 表,代码里不写死任何服务器参数。MailService 是实例类,必须先 new。

SMTP 配置项

设置键说明
smtp_hostSMTP 主机,默认 localhost
smtp_port端口;465 自动走 ssl,587 自动走 tls,其他端口不加密
smtp_user账号
smtp_pass密码
smtp_from发件地址;非法时回退到 smtp_user,再回退 noreply@localhost
smtp_fromname发件人名称,默认取 site_name

发送

send 返回 ['ok'=>bool,'msg'=>?]
$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 封会把请求拖到超时。

14

设备判断与蜘蛛识别

框架提供三个全局函数做设备判断,全部可传自定义 UA(不传则读 $_SERVER['HTTP_USER_AGENT'])。判定规则只有一份,插件调用与框架内部走的是同一套逻辑。

device_type / is_mobile / is_pc
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'

判断顺序

内部逻辑分两步,顺序不能颠倒:

  1. 先匹配"桌面 / 平板"特征:iPad|Tablet|PlayBook|Silk|Macintosh|Windows NT|Windows OS。命中这些通常判 PC。
  2. 但 UA 里含 iPad 时不直接判 PC,继续往下走——因为 iPad 的 UA 同时带 Macintosh 和 Mobile 特征。
  3. 再匹配移动特征:Android|iPhone|iPod|Symbian|Windows Phone|Mobile|HarmonyOS|MiuiBrowser,以及 MicroMessenger 同时带 iPhone|Android(微信内置浏览器)。命中任一即 mobile。
  4. 都不命中 → PC。

这套顺序解决了"平板被误判成手机"和"iPad 被误判成 Mac"两个常见问题。想按自己的规则判(例如把平板单独算一类),拿 UA 自己写,is_mobile 只给"二选一"的答案。

蜘蛛识别

CommonService::isSpider 无参
$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 可以伪造,新设备也会漏判。不要用它做权限或安全判断,只用于展示层适配。

15

二维码:后端生成,前端解码

二维码能力被刻意拆成两半:生成在 PHP 侧(服务端出图,保证每个访客拿到同一张、可缓存、可落盘),解码在浏览器侧(jsQR,读摄像头或上传的图片)。PHP 侧没有解码器,也不打算加——那需要额外扩展或臃肿的纯 PHP 实现,与"零环境依赖"冲突。

生成:五个函数

函数返回用途
qr_code_library()bool运行环境是否具备生成能力(依赖 vendor/QR/phpqrcode.php)
qr_code_png($content, $opts=[])?stringPNG 二进制;失败返回 null
qr_code_data_uri($content, $opts=[])stringdata: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="" assign=""}
{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 校验)。

16

安全 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

表单与 AJAX 两种提交方式
<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。

密码

不要自己调 password_hash
$hash = Security::hashPassword($plain);
$ok   = Security::verifyPassword($plain, $hash);

验证码

HTML 渲染与校验
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 闭环

校验顺序:方法 → CSRF → 字段 → 落库 → 反馈
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 定义渲染表单。

17

语言包与国际化的落地

语言包就是"返回数组的 PHP 文件",一个语言一个文件。插件、主题各有自己的语言目录,互不干扰;缺哪个键就回退到默认文案,不会报错。

目录与格式

plugins/demo/lang/zh-cn.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。

读取

get / pluginGet 支持 sprintf 参数
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 文件、写入语言元数据表并记录来源路径。插件一般不需要调用它们——除非你要在自己的设置页里做"一键安装语言包"。

案例:插件双语 + 模板取词

main.php 注册 + 页面用 pluginGet + 模板用 {t}
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 占位符的数量要与调用处一致,多传少传都不会报错,但文案会缺一块。

18

视图、模板与模板标签

视图层是 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取当前变量、主题名、底层实例

模板覆盖链:谁先命中谁生效

顺序目录来源
1templates/{当前主题}/views/默认注册
2templates/default/views/默认注册,作为兜底
3插件与第三方追加的目录view_template_dirs 过滤器
在 main.php 里登记自己的模板目录
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 的完整骨架

templates/demo/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 的目录链。

19

路由注册与页面入口

前台路由只有一条正规注册途径:router_routes 过滤器。除此之外的 URL 形态都由框架内置的三条默认路由接管,插件不要试图改 index.php 的分发逻辑。

注册自定义路由

pattern 是正则,handler 是 Class@method
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 并在入口文件显式引入。

默认路由

patternhandler说明
#^plugin/(\w+)(?:/(\w+))?$#PluginPageController@handle前台插件页统一入口
其余已配置的站点路由各自的控制器首页、书库、详情、阅读、榜单、作者、用户中心等
未命中NotFoundController@index渲染主题 404.tpl,http_response_code(404)

案例:一个能跑通的自定义路由控制器

plugins/demo/controllers/DemoProbeController.php
<?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,框架会:

  1. 用 Security::validPluginId 校验 id,不合法直接 404;
  2. 用 Plugin::isEnabled 校验启用状态,未启用返回 404;
  3. define('PLUGIN_PAGE_ACCESS', true),然后 Hook::doAction('plugin_page_demo_stats', $this);
  4. require plugins/demo/pages/stats.php。
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=demoplugins/demo/admin.php 存在则渲染它;不存在则看 PluginConfig::fields('demo'),非空时自动渲染配置表单(POST 经 CSRF 校验后 PluginConfig::save)
?action=plugin_page&pid=demo&page=statsplugins/demo/pages/stats.php
经 admin_plugin_pages 注册的自定义 action如 ?action=crawl,键是 action 名,值是页面文件绝对路径
经 admin_menu 挂菜单只是导航入口,落点仍是上面三种之一
注册后台页面(crawler 的真实写法)
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 自动帮你挡掉停用状态——用前台插件页。

20

后台界面扩展

后台扩展分四类:加菜单、加页面、给已有列表加列、给已有编辑页加字段。前两类是自己造界面,后两类是往别人的界面里插东西——这两类的收益最高,代码也最少。

加菜单:两种写法

声明式(推荐)
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' => ...) 不会报错,但菜单项会渲染成空白。

改页面标题

admin_page_title
Hook::addFilter('admin_page_title', function ($title, $action) {
    if ($action === 'demo_stats') {
        return '统计看板';
    }
    return $title;
}, 10, 'plugin:demo');

第二个参数是当前 action。返回空串会让标题区变成空白,所以不要 return null——返回原值。

给已有列表加列:PluginTable

注册一列(键用 admin.页面名)
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数值字符串
switch1 / 0
select / radio选项值
checkbox1 / 空
checkbox_group / multiselectJSON 数组字符串

提交值统一走 $_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

不要在每个页面手写 link 标签
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 里做查询——它每个后台页都会执行,会拖慢整个后台。

21

网络请求与内容工具

采集、外链校验、第三方 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 字符串——池里的版本会跟着更新。

案例:抓一页、清洗、落库

带 UA、带失败分支、带日志
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。如果先数字数再清洗,被剥掉的标签和样式会被算进字数里,站内统计会偏大。

22

支付网关与定时任务

这两块都是"接口型扩展":框架定好抽象类或触发点,插件实现具体逻辑。它们的共同点是没有 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 的一次性保证,在重复加载时容易重复注册。

案例:一个最小可用的网关骨架

plugins/demo/lib/DemoGateway.php + main.php 注册
<?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 与 cron_run 钩子
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 输出会进邮件或被截断,只写日志。

23

状态码与错误处理

站点对"错误"有两套处理:可预期的(资源不存在、没权限、请求太频繁)走状态码 + 主题 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,只需把状态码和页面交给现有链路:

控制器里主动 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));
}
接口的 405 与 429
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 + 日志"收进一个函数,比在每个分支里手写三行更不容易漏。注意日志里写的是给运维看的信息,返回给客户端的是给用户看的信息,两者不要混用同一句话。

24

开发红线

这一章是"必须遵守,没有例外"的清单。前九条是这套系统当前强制的规范,第十条是交付前自查。

1. 注释:一个文件只留一条

全站口径是每个脚本文件顶部只保留一条页面功能说明,其余注释一律删除。这里的"脚本"包括 PHP、CSS、JS、模板。

文件类型保留必须删除
PHP文件顶部 1 条,≤40 字,说明这个文件干什么类注释、方法注释、行内注释、分节注释、被注释掉的旧代码
CSS无分区标题、属性说明、被注释的样式
JS无函数说明、调试日志、被注释的代码
模板(tpl / html)无<!-- --> 注释、分节标记
PHP 文件的正确形态
<?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),避免与系统函数或别的插件重名。

25

上线检查与排错

必须文件

类型必须说明
插件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 有 CSRFSecurity::verifyCsrf() 在写操作前
9所有输出有转义用户可控内容过 Security::h()
10SQL 无拼接手写 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()
控制器没 requireClass 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(钩子 + 配置 + 二维码 + 日志的完整样本),这两个是最贴近真实用法的参考实现。遇到手册没覆盖的细节,以这两个目录里的代码为准。

26

公共 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
站点 URLurl($route, $params) url_full()url 返回站内路径(不含 BASE_URL),url_full 带域名前缀
页面 URLnovelUrl 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 / assignPNG 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 count10
QueryBuilder链式条件where select orderBy groupBy limit get first count paginate10
PluginDB插件表insert find findById all update delete count paginate search10
ChapterShard章节分片按 SHARD_SIZE 定位分表的读写入口10
Hook动作与过滤器addAction addFilter doAction applyFilters suspendOwner removeOwner5、6
Cache四驱动缓存get set delete flush remember11
Logger文件日志plugin theme readPlugin readTheme clearPlugin extensions12
Security转义、CSRF、上传h csrfToken verifyCsrf hashPassword input verifyImageUpload safeFilename16
Language系统与扩展语言包get pluginGet registerPlugin current jsStrings17
Theme主题注册与配置activePc activeMobile scanAll enable typeOf supports readManifest9
Plugin插件注册与配置isEnabled enabledIds all config setConfig createTable view8
Extension统一扩展内核load info conf menu setting sidebar table field cacheGet cacheSet7
ViewSmarty 封装init assign assignArray fetch render addTemplateDir18
NetworkHTTP 客户端get post request download isSafeUrl21
MailServiceSMTP 发信new MailService -> send sendVerifyCode13
CommonService内容与爬虫判断isSpider smartWordCount formatNumberShort sanitizeRichText21
Cron定时任务tasks runAll warmCache cleanup22
Ui前后台资源注入registerFront registerAdmin20
PaymentGateway支付接口契约getId getName isEnabled createOrder verifyNotify parseNotify22
PaymentGatewayRegistry网关注册表load register get enabled22
ErrorHandler统一错误页register23

另有 PluginConfig、PluginForm、PluginTable、ThemeConfig、AdminLanguage 五个组件类,分别服务配置表单、表单字段注入、列表渲染、主题配置与后台语言包;它们由框架在对应页面里调用,插件一般不直接 new。

四、页面级变量

这些变量不是函数,是渲染前已经放在作用域里的值,直接用就行。

主题模板(.tpl)

变量含义
$siteName $siteKeywords $siteDesc $siteLogo站点基础信息与 logo 地址
$themeUrl当前主题根 URL(BASE_URL . '/templates/' . 主题)
$csrf_token当前会话 CSRF token,配合 {csrf_field}
$seotitle / 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)

变量含义
$dbDatabase 实例
$requestRequest 实例,取参数与用户
$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

plugins/demo/pages/index.php
<?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。

主题模板:资源地址不写死

templates/{主题}/views/header.tpl
<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,不要写死目录名。

27

嵌入点总表

全站一共 84 处触发点、74 个名称,分成动作(doAction,只通知,无返回值)与过滤器(applyFilters,必须返回被改过的值)两类。下面按前台、数据层、后台、输出链分组,名称与参数都取自源码,参数名以触发处实际传入的为准。

一、前台动作

名称参数触发位置用途
core_before_controller$controller, $actionRouter::dispatch 进控制器前全局前置:鉴权、埋点、限流
core_after_controller$controller, $action控制器返回后全局后置:收尾、统计
user_login_success$user, $_POSTUserController 登录成功登录奖励、同步第三方
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$routesRouter 建表时注册自定义路由
library_filters$filters, $requestLibraryController改书库筛选条件集合
library_where['where','params'], $filtersNovelModel往书库查询追 SQL 条件
library_order_sql$orderSql, $orderBy, $filters同上换排序语句
library_order_options$ordersLibraryController加排序选项
library_order_labels$labels同上排序选项的显示名
library_status_labels$labels同上状态筛选项名
library_vip_labels$labels同上VIP 筛选项名
rank_types$validRankController加榜单类型
rank_type_labels$labels同上榜单类型显示名
rank_order_sql$order, $type, $timeRangeNovelModel换榜单排序字段
diy_block_where['where','params'], $blockNovelServiceDIY 区块查询条件
diy_block_order_sql$orderBy, $block同上DIY 区块排序
diy_block_fields$fields, $block同上DIY 区块额外字段
captcha_verifynull, $inputSecurity::verifyCaptcha接管验证码校验,返回 true/false
captcha_render_html$defaultHtml, $name, $placeholderSecurity::captchaHtml换验证码渲染
view_template_dirs$dirsView::init加模板查找目录
view_before_render$vars, $templateView::render渲染前改全部变量
view_template$template, $vars同上换模板文件
output_filter$html, $templateView::render 输出前改最终 HTML
payment_gateways$gatewaysPaymentGatewayRegistry::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$nVIP 审核行行内按钮
admin_volumes_row_actions$v, $novelId分卷列表行行内按钮
admin_withdraw_row_actions$row提现列表行行内按钮

五、后台过滤器

名称参数触发位置用途
admin_menu$menuGroupsadmin/includes/sidebar.php往侧栏菜单加分组或条目
admin_plugin_pages$pagesadmin/index.php注册 ?action=xxx 映射到插件文件
admin_page_title$title, $action后台标题改页面标题
admin_novel_save_data$data作品保存前入库前改字段
diy_status_options / diy_time_options / diy_order_options$optionsDIY 区块配置页加筛选项

六、案例

给作品列表行加一个按钮

admin_novels_row_actions
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,做跨表操作时用得上。

给书库加一条查询条件

library_where
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 里同时补上,否则用户根本选不到这个条件。

28

页面数据地图

主题开发要天天用的那张表:一个页面对应哪个控制器方法、渲染哪个 .tpl、模板里能拿到哪些变量、这些变量里的列表从哪个方法出来。这一章按页面顺序铺开。

一、变量从哪来

控制器里写 $this->view('library.tpl', $data),第二个参数的每个键就是模板里的同名变量。在这之前,Controller::init() 已经塞了一批全局变量,任何页面都能直接引用。

变量内容
$siteName / $siteKeywords / $siteDesc后台站点设置
$siteLogo优先 data/uploads/theme_logos/{主题}.png,没有则用后台 site_logo
$themeUrlBASE_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::indexhome.tpl
书库library 前缀,可带分类与筛选段LibraryController::indexlibrary.tpl
排行榜rank 前缀 + 类型RankController::indexrank.tpl
作品详情novel 前缀 + 作品 id(可带章节页码)NovelController::detailnovel_detail.tpl
阅读页read 前缀 + 作品 id + 章节 idReadController::indexread.tpl
搜索search 前缀SearchController::indexsearch.tpl
作者列表authorsAuthorController::indexauthors.tpl
作者主页author 前缀 + 用户 idAuthorController::detailauthor_detail.tpl
用户中心user/{action}UserController::handleuser/index.tpl、user/login.tpl、user/bookshelf.tpl 等
作者中心authorcenter/{action}AuthorCenterController::handleauthor/works.tpl、author/chapter_list.tpl 等
支付回跳pay/returnPayController::handleuser/pay_return.tpl
404未匹配任何路由NotFoundController::index404.tpl
插件前台页plugin/{id}/{page}PluginPageController::handleplugins/{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分类树
$filterscategory_id / order_by / vip_filter / status / keyword / min_words / max_words
$currentCategory当前分类 id,整数
$orderOptions / $orderLabels排序键数组(如 update)与对应显示名
$statusLabels / $vipLabelsall / 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 字预览
$permallowed / 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 条件
status0 连载 / 1 完本status = 0 / status = 1
is_vip0 免费 / 1 VIPis_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(不限)或逗号串
statusall / ongoing / finished
time_rangeall / today / week / month / year,按入库时间
order_byviews / 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 不在首页出现,专供详情页相关推荐。

案例:在主题里把自定义榜单挂到首页

include.php
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 会让整页变量变空。

案例:模板里渲染这个榜单

home.tpl
{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}

案例:模板里读筛选现状与选项名

library.tpl
<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 章。

EnovelCms 3.0 插件与主题开发手册 · 2026-11-15 按需查阅 · 案例可直接复制运行