README

adminmatrix/matrix_plugin 是一个基于 ThinkPHP 8.1+ 的轻量插件系统，提供：

• 插件目录自动创建（安装/更新 composer 后自动生成 plugins/）
• 插件脚手架（快速生成插件目录结构与示例控制器）
• 插件安装/卸载命令（支持依赖安装、数据库迁移）
• 插件迁移命令（create/run/rollback/status）
• 插件列表查询

该包会通过 composer.json -> extra.think.services 自动注册服务：adminmatrix\plugin\Service，用于加载命令与插件初始化能力。

运行环境

• PHP: ^8.3
• ThinkPHP: ^8.1（topthink/framework）

安装

在你的 ThinkPHP 项目根目录（有 think 命令的目录）执行：

composer require adminmatrix/matrix_plugin

安装完成后，会自动执行脚本创建插件目录：

• plugins/

对应脚本：adminmatrix\plugin\Scripts::createPluginsDir（composer post-install-cmd / post-update-cmd）。

插件目录结构

默认插件目录位于项目根目录：

plugins/
  demo/
    controller/
    model/
    service/
    common.php
    event.php
    middleware.php
    module.json

其中：

• module.json：插件元信息（名称、版本、作者、安装状态等）
• common.php：插件公共函数/辅助方法（会在插件加载时自动 include）
• event.php：插件事件监听定义（加载时自动注册）
• middleware.php：预留插件中间件定义（是否启用取决于你的应用集成方式）

创建插件（脚手架）

使用命令创建一个插件（会生成目录与基础文件）：

php think plugin:make demo

该命令会在 plugins/demo/ 下生成基础结构，并创建一个示例控制器（通常为 Index 或 IndexController，取决于 route.controller_suffix 配置）。

生成的命名空间规则：

• 插件 demo 的根命名空间为：plugins\demo
• 控制器命名空间为：plugins\demo\controller

插件列表

查看当前 plugins/ 下所有插件及安装状态：

php think plugin:list

会读取每个插件的 module.json 并以表格形式输出：

• 插件标识（目录名）
• 插件名称
• 版本号
• 描述
• 作者
• 安装状态（已安装/未安装）
• 插件类型（module.json 的 type 字段）

安装插件

安装逻辑依赖插件目录下的配置文件与迁移文件。

执行：

php think plugin:install --plugin=demo
# 或
php think plugin:install -p demo

安装过程主要包含：

1. 读取 plugins/demo/config.json（注意：当前版本安装命令读取的是 config.json）
2. 检查是否需要安装 composer 依赖（插件目录存在 composer.json 时）
3. 检查是否存在数据库迁移（plugins/demo/database/migrations/*.php）
4. 执行依赖安装、迁移运行等步骤

备注：plugin:install 内部会尝试执行迁移命令（示例里写死了命令字符串），你可以根据项目需要进行二次集成/修正。

数据库迁移（Migrate）

该包提供一组迁移相关命令（以实际注册为准）：

• plugin:migrate_create（创建迁移文件）
• plugin:migrate_run（执行迁移）
• plugin:migrate_rollback（回滚迁移）
• plugin:migrate_status（查看迁移状态）

你可以通过 ThinkPHP 命令列表确认：

php think list | findstr plugin

运行时加载（HTTP 请求进入插件）

该包内置 adminmatrix\plugin\Service，在 register() 中会根据请求参数尝试将请求路由到 plugins/{plugin}/...。

典型思路（按当前代码实现）：

• 当请求参数 s 以 /app 开头时，匹配路由 app/:any
• :any 用作插件名（例如 demo）
• 动态切换：
  • appPath => plugins/{demo}/
  • namespace => plugins\{demo}
  • runtimePath => runtime/plugins/{demo}
• 自动加载插件的 common.php
• 自动注册插件 event.php 中声明的事件
• 根据 URL 解析出控制器/方法并调用

注意：要让 plugins\demo\controller\IndexController 能被 class_exists() 正确加载，通常需要确保插件命名空间与自动加载机制匹配（例如通过 Composer PSR-4 或框架自定义 Loader）。

插件 module.json 说明

plugin:make 会生成 module.json，示例：

{
  "name": "Demo",
  "alias": "demo",
  "description": "demo 插件 ,由系统创建",
  "version": "1.0.0",
  "author": "系统创建",
  "type": 1,
  "keywords": [],
  "priority": 0,
  "service": [],
  "files": [],
  "status": false
}

字段含义（约定）：

• alias：插件标识（一般与目录名一致）
• status：是否安装启用（plugin:list 会展示，运行时也可能据此拦截）
• service / files：预留扩展（按你的业务自行定义加载策略）

常见问题（FAQ）

1）访问不存在页面变成 200 空响应？

如果你用 route->rule('app/:any', function(){}) 这种“兜底闭包路由”拦截请求，但没有返回/抛异常，会导致 200 空响应。

建议在兜底时显式：

abort(404);

或把“判断是否进入插件”的逻辑放到中间件，而不是闭包兜底路由。

2）class_exists("plugins\demo\controller\IndexController") 为 false？

说明插件目录未纳入自动加载范围。通常需要：

• 确保命名空间使用反斜杠：plugins\\demo
• 并在项目 composer.json 中加入：

{
  "autoload": {
    "psr-4": {
      "plugins\\": "plugins/"
    }
  }
}

然后执行：

composer dump-autoload

License

MIT