小枫_QWQ 项目文档站

Appearance

2026-08-13
895
3.5m

插件机制功能概览 ​

1. 完整的插件生命周期管理 ​

插件支持五个生命周期钩子，由 Plugin.php 定义：

方法触发时机用途
install()插件首次安装时创建数据库表、初始化数据
uninstall()插件卸载时清理数据库表、删除数据
activate()插件启用时启用时的初始化工作
deactivate()插件禁用时禁用时的清理工作
boot()每次请求加载插件时注册服务、初始化运行时状态

2. 路由扩展能力 ​

插件可以向系统路由表中注入自定义路由，格式与 AppConfig 完全一致：

php
protected array $routes = [
    'public' => [
        ['GET', '/oauth/github/login', [self::class, 'redirectToGitHub']],
        ['GET', '/oauth/github/callback', [self::class, 'handleCallback']],
    ],
    'admin' => [
        ['GET', '/sample-plugin', [self::class, 'adminPage']],
    ],
];

路由会自动合并到对应的路由组（public、admin、user、api），无需修改主程序代码。

3. Hook 事件监听系统 ​

系统级 Hook（SystemHook.php） ​

Hook参数触发时机
Boot-框架启动后、路由分发前
UserRegistereduser用户注册成功后
UserLoggedInuser用户登录成功后
OrderCreatedorder订单创建后
OrderPaidorder订单支付成功后
OrderCancelledorder订单取消后
LicenseCreatedlicense授权创建后
LicenseExpiringlicense授权即将到期时
LicenseExpiredlicense授权到期后
ViewRenderBeforeviewName, data视图渲染前
ViewRenderAfterviewName, html视图渲染后
AdminNavigationnavItems后台侧边栏渲染时
UserNavigationnavItems用户端导航渲染时
UserSettingsSectionuser用户设置页面渲染时

应用级 Hook（AppHook.php） ​

Hook参数触发时机
PiracyRecordVerifiedpiracyRecord盗版线索核验入库后
PiracyRecordClosedpiracyRecord盗版线索关闭后
SupportTicketCreatedticket用户提交工单后
SupportTicketRepliedticket, reply客服回复工单后
CardsGeneratedcards卡密生成后
CardRedeemedcard, license卡密核销后
PaymentChannelschannels（引用传递）注册支付通道时
PaymentCheckoutchannel, order, product支付下单时
PaymentNotifychannel, payload, headers, orderNo支付回调时

短路机制：Hook 处理器返回 false 可阻止后续处理器执行。

4. 插件配置管理 ​

插件可以定义配置项，系统自动生成配置表单并持久化到数据库：

php
protected array $settings = [
    'client_id' => ['type' => 'string', 'label' => 'Client ID', 'default' => ''],
    'auto_create' => ['type' => 'bool', 'label' => '自动创建新用户', 'default' => true],
];

支持的配置类型：string、bool、int、textarea。

5. 插件依赖管理 ​

支持声明插件间的依赖关系，支持语义化版本约束：

php
protected array $dependencies = [
    'GitHubOAuth' => '^1.0.0',  // 需 >=1.0.0 <2.0.0
    'SomePlugin' => '>=2.0.0',  // 需 >=2.0.0
];

启用插件时自动验证依赖，禁用插件时检查是否有其他插件依赖它。

6. 数据库表前缀保护 ​

插件创建数据库表时，通过 $this->table('table_name') 方法自动添加前缀 plugin_插件名_，避免表名冲突：

php
// GitHubOAuth 插件调用 table('oauth_accounts') 返回
// plugin_GitHubOAuth_oauth_accounts
$t = $this->table('oauth_accounts');

7. 视图扩展能力 ​

通过 ViewRenderBefore 和 ViewRenderAfter Hook，插件可以在特定视图中注入内容。例如 GitHubOAuth 插件在登录页面渲染后自动插入 GitHub 登录按钮。

8. 管理后台集成 ​

后台 /admin/plugins 提供：

  • 插件列表展示（名称、版本、作者、描述、启用状态）
  • 启用/禁用插件操作
  • 插件配置页面（自动根据 $settings 生成表单）
  • 重置配置功能

内置插件示例 ​

SamplePlugin ​

演示插件机制的基本用法：路由注册、Hook 监听、配置项定义。

GitHubOAuth ​

提供完整的 GitHub OAuth 登录功能：

  • 登录页面自动注入 GitHub 登录按钮
  • 支持已有账户关联和新用户自动创建
  • 用户设置页面展示第三方账号绑定状态
  • 自定义数据库表存储 OAuth 关联信息
最近更新