Z-BlogPHP 插件开发入门：RegisterPlugin、Add_Filter_Plugin、main.php 怎么配合？先别急着背 Hook

如果说主题开发解决的是“站点怎么长”，那插件开发更像是在解决：

站点某个流程怎么接管、怎么增强、怎么复用。

但很多人第一次学 Z-BlogPHP 插件时，会被几个点同时卡住：

• plugin.xml 是做什么的
• RegisterPlugin(...) 到底注册了什么
• Add_Filter_Plugin(...) 到底把逻辑挂到了哪
• main.php 又为什么经常一起出现

这篇就专门把插件开发最基础的骨架讲清楚。

一、先记住：插件不是换皮，插件是接流程

主题开发和插件开发最根本的差异，不是目录不同，而是职责不同。

主题更偏：

• 页面结构
• 前台外观
• 主题级配置

插件更偏：

• 功能扩展
• 流程插入
• 后台增强
• 评论和接口处理
• 字段注入
• 通用逻辑复用

所以你学插件开发时，脑子里要先切换一个视角：

你不是在“写一个页面”，而是在“接管一个系统阶段”。

二、一个最小可用插件，目录通常长这样

zb_users/plugin/<plugin>/
├── plugin.xml
├── include.php
├── main.php
├── includes/
└── vendor/

你第一次做插件，不一定全都用上。

但至少这三个位置，最好尽早理解：

• plugin.xml
• include.php
• main.php

三、plugin.xml 是插件元信息，不是行为实现层

它和主题里的 theme.xml 很像，主要负责插件的基础身份信息。

通常包括：

• 插件 ID
• 插件名称
• 版本
• 作者
• 后台入口

一个简化示意大概像这样：

<?xml version="1.0" encoding="utf-8"?>
<plugin version="php">
  <id>MyPlugin</id>
  <name>My Plugin</name>
  <note>一个用于演示 Hook 注册的插件</note>
  <path>main.php</path>
  <level>1</level>
</plugin>

这里最重要的不是字段多复杂，而是：

• 插件 ID 稳定
• 目录名和 ID 尽量一致
• 后台入口路径明确

四、include.php 才是插件真正开始生效的地方

如果你想知道一个插件“到底从哪开始挂进系统”，答案通常就是：

include.php

因为插件最关键的两步，通常都会在这里开始：

1. 注册插件
2. 注册 Hook

最常见的入口骨架就是：

RegisterPlugin("MyPlugin", "ActivePlugin_MyPlugin");

function ActivePlugin_MyPlugin() {
    Add_Filter_Plugin('Filter_Plugin_Zbp_Load', 'MyPlugin_Init');
}

function MyPlugin_Init() {
}

这段代码要怎么理解？

RegisterPlugin(...)

它的意思可以简单理解成：

告诉系统，这个插件的激活入口函数是谁。

ActivePlugin_MyPlugin()

这个函数通常是插件启用后开始挂接逻辑的地方。

Add_Filter_Plugin(...)

这个才是把具体行为挂到某个系统阶段里去。

也就是说，真正的关键不只是“写一个函数”，而是：

把函数挂到对的阶段。

五、为什么 Add_Filter_Plugin(...) 是插件开发的核心

因为 Z-BlogPHP 的插件机制，很大一部分就是靠 Hook 驱动的。

这意味着：

• 你不需要改系统核心文件
• 你不需要复制整条平台流程
• 你只需要在合适的时机插进去

这也是插件比硬改核心更稳的原因。

比如你想做的事情可能是：

• 评论前做校验
• 文章编辑页加字段
• 后台列表多一列
• 前台页面在某个阶段补充数据
• 注册一个自定义路由

这些都不是“重写整个系统”，而是“找到正确 Hook 再挂进去”。

六、main.php 在插件里通常负责什么

很多人第一次看插件，会误以为 main.php 是主逻辑文件。

其实它更像：

插件的后台管理入口。

最常见的职责包括：

• 权限检查
• 插件启用检查
• 表单保存
• 配置项管理
• 简单后台工具页

所以一个插件的职责通常是这样分：

• plugin.xml：身份信息
• include.php：挂接逻辑
• main.php：后台设置和管理

只要这层分工一清楚，插件目录就不会越写越乱。

七、一个“最小插件”可以先做成什么样

第一次写插件，不建议一上来就做特别重的东西。

更稳的起点是做一个很小但路径完整的功能。

比如：

• 给后台加一个设置页
• 给前台某类页面挂一个小开关
• 给文章页增加一个可配置提示区

这类需求的好处是：

• 容易看出插件入口
• 容易练到配置保存
• 容易理解 Hook 是怎么插进去的

八、插件配置项怎么和主题配置项区分

它们保存方式很像，都是：

$zbp->Config('AppID')->SomeKey = $value;
$zbp->SaveConfig('AppID');

但职责不同。

更适合做成插件配置的

• API Key
• 开关规则
• 评论审核策略
• 后台功能项
• 复用模块参数

更适合做成主题配置的

• 首页主标题
• 默认缩略图
• 页脚文案
• 主题展示开关

也就是说：

和功能流程绑定的，更像插件配置。
和站点外观绑定的，更像主题配置。

九、写插件时，先怎么判断应该挂哪个 Hook

很多新手不是不会写函数，而是不知道函数该挂哪。

你可以先按需求类别判断：

要改前台页面准备逻辑

优先关注：

• Filter_Plugin_ViewList_Core
• Filter_Plugin_ViewPost_Core
• 相关视图阶段 Hook

要改模板选择或页面模板行为

优先关注：

• Filter_Plugin_ViewList_Template
• Filter_Plugin_ViewPost_Template

要改后台菜单、后台表格、编辑页

优先关注：

• 后台菜单 Hook
• 后台表格 Hook
• Edit_Response 系列 Hook

要改评论流程

优先关注：

• Filter_Plugin_PostComment_Core
• Filter_Plugin_CheckComment_Core
• Filter_Plugin_Error_Handler

要做路由或早期请求处理

优先关注：

• Filter_Plugin_Zbp_PreLoad
• Filter_Plugin_Zbp_Load

你会发现，插件开发最重要的技能之一，不是写多复杂，而是：

先把需求归类，再找 Hook 家族。

十、什么时候应该把逻辑从主题里抽成插件

这是很多项目后期都会遇到的问题。

如果某段逻辑开始出现这些特征，就该认真考虑插件化：

• 多主题都可能复用
• 不只影响模板结构
• 涉及后台页面
• 涉及评论、接口、校验、路由
• 明显属于功能，不属于页面长相

反过来，如果某段逻辑：

• 强绑定当前主题
• 只服务某个页面的视觉结构
• 换主题就没有意义

那它大概率还是主题职责。

十一、插件开发里最常见的 6 个坑

1. plugin.xml 只是建了，但没建立清晰入口

结果后面自己都找不到插件从哪开始生效。

2. Hook 注册和具体实现全塞一个超长文件

前期还好，后面会越来越难读。

3. 一开始就写过重插件

更好的起点是：

• 先做一个完整的小功能
• 先把注册、Hook、配置页跑通

4. 把主题专属展示逻辑全抽成插件

最后职责会变得很拧巴。

5. 配置页能保存，但前台或流程根本没消费

这和主题配置项是同一个坑型。

6. 找 Hook 时不按家族找，直接硬搜全站

效率会很低。

十二、第一次写插件，建议你这样练

我更建议你用这个顺序练手：

1. 建插件目录
2. 写 plugin.xml
3. 写 include.php
4. 完成 RegisterPlugin(...)
5. 挂一个最简单的 Hook
6. 新建 main.php
7. 做一个最小设置项
8. 验证插件启用、保存、前台或后台生效

只要这条链路你跑通一次，后面再学评论插件、后台扩展插件、API 插件，都会容易很多。

结语

Z-BlogPHP 插件开发最重要的，不是先记住几十个 Hook 名字，而是先建立这套骨架理解：

• plugin.xml 负责身份
• include.php 负责注册和挂接
• main.php 负责后台设置和管理
• RegisterPlugin(...) 负责告诉系统入口
• Add_Filter_Plugin(...) 负责把逻辑挂到正确阶段

你只要先把这套配合关系想明白，插件开发就已经真正入门了。

下一篇我们专门讲 Hook 怎么找、怎么用，把这套挂接思路再往前推进一步。