# matrix_plugin

**Repository Path**: adminmatrix/matrix_plugin

## Basic Information

- **Project Name**: matrix_plugin
- **Description**: thinkphp 插件
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-04-27
- **Last Updated**: 2026-01-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# matrix_plugin（ThinkPHP 8 插件系统）

`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` 命令的目录）执行：

```bash
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`：预留插件中间件定义（是否启用取决于你的应用集成方式）

---

## 创建插件（脚手架）

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

```bash
php think plugin:make demo
```

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

生成的命名空间规则：

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

---

## 插件列表

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

```bash
php think plugin:list
```

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

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

---

## 安装插件

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

执行：

```bash
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 命令列表确认：

```bash
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`，示例：

```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 空响应。

建议在兜底时显式：

```php
abort(404);
```

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

### 2）class_exists("plugins\\demo\\controller\\IndexController") 为 false？
说明插件目录未纳入自动加载范围。通常需要：

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

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

然后执行：

```bash
composer dump-autoload
```

---

## License

MIT