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

安装过程主要包含：

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

备注：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

adminmatrix / matrix_plugin

Maintainers

Details