---
url: /docs/5.0/plugin/helper.md
---
# Plugin 辅助方法

> `Plugin` 类提供了一系列静态方法，帮助你在插件开发中快速完成常见任务，如创建菜单、执行迁移、发布资源等。

## 引入方式

```php
use Catch\Plugin\Support\Plugin;
```

## 菜单相关

### createMenus - 批量创建菜单

批量导入菜单数据到系统。

```php
Plugin::createMenus([
    Plugin::createMenu('插件名称', '/route', 'Namespace', children: [
        // 子菜单...
    ])
]);
```

### createMenu - 创建单个菜单

创建菜单数据结构，通常与 `createMenus` 配合使用。

```php
Plugin::createMenu(
    name: '菜单名称',           // 菜单显示名称
    frontRoute: '/path',        // 前端路由
    module: 'Test\Test',        // 模块命名空间
    icon: 'icon-name',          // 图标（可选）
    controller: 'UserController', // 控制器名（可选）
    controllerMethod: 'index',  // 控制器方法（可选）
    type: 1,                    // 类型：1=目录 2=菜单 3=按钮
    component: '',              // Vue 组件路径（可选）
    activeMenu: '',             // 激活菜单（可选）
    children: [],               // 子菜单（可选）
    extra: [
        'hidden' => 2 // 额外数据（可选）
    ]
);
```

:::tip 🎨 关于图标
菜单图标使用 [Heroicons](https://heroicons.com/)，这是一套由 Tailwind CSS 团队设计的精美 SVG 图标库。

使用方式：直接填写图标名称（无需前缀），例如：

* `home` - 首页图标
* `users` - 用户图标
* `cog-6-tooth` - 设置图标
* `document-text` - 文档图标

访问 https://heroicons.com/ 浏览所有可用图标。
:::

**完整示例：**

```php
public function afterInstall(array $context): void
{
     Plugin::createMenus([
            Plugin::createMenu(
                name: '系统管理',
                frontRoute: '/system',
                module: 'system',
                icon: 'server-stack',
                children: [
                    Plugin::createMenu(
                        name: '定时任务',
                        frontRoute: 'cron/tasks',
                        module: 'system',
                        controller: 'cronTasks',
                        type: 2,
                        component: Plugin::view('modules/system-cron', 'cronTasks.index')
                    ),
                    Plugin::createMenu(
                        name: '定时任务日志',
                        frontRoute: 'cron/log',
                        module: 'system',
                        controller: 'cronTasksLog',
                        type: 2,
                        component: Plugin::view('modules/system-cron', 'cronTasksLog.index'),
                        extra: ['hidden' => 2]
                    ),
                ]
            ),
        ]);
}
```

## 视图相关

### view - 生成插件视图 URL

生成插件 Vue 页面的访问路径。

```php
Plugin::view('vendor/plugin', 'users.index');
// 返回: api/plugins/vendor/plugin/users/index
```

| 参数 | 说明 | 示例 |
|------|------|------|
| `$plugin` | 插件包名 | `'my/plugin'` |
| `$entry` | 入口文件（点号分隔） | `'users.index'` |
| `$prefix` | URL 前缀（默认 `api/plugins`） | `'api/plugins'` |

### render - 动态渲染 Vue 页面

获取 Vue 页面内容及其依赖文件。

```php
$result = Plugin::render('my/plugin', 'users/index.vue');
// 返回: ['entry' => '/users/index.vue', 'files' => [...]]
```

### publishView - 发布视图到前端目录

将插件视图发布到 `web/src/views/` 目录。

```php
Plugin::publishView($pluginViewPath, 'my-plugin');
// 发布到: web/src/views/my-plugin/
```

### deleteView - 删除已发布的视图

```php
Plugin::deleteView('my-plugin');
```

## 数据库相关

### migrate - 执行数据库迁移

执行指定路径的迁移文件。

```php
Plugin::migrate(Plugin::getPluginPath('test/test') . DIRECTORY_SEPARATOR . 'migrations');
```

OR

```php
Plugin::migrate(Plugin::getPluginPath($context['name']) . DIRECTORY_SEPARATOR . 'migrations');
```

### seed - 执行数据填充

```php
Plugin::seed(\Database\Seeders\MySeeder::class);
```

### migrateModule - 执行模块迁移

```php
Plugin::migrateModule('MyModule');
```

### seedModule - 执行模块数据填充

```php
Plugin::seedModule('MyModule');
// 或指定 Seeder
Plugin::seedModule('MyModule', MySeeder::class);
```

## 模块相关

### publishModule - 发布模块

将模块文件发布到 `modules/` 目录。

```php
Plugin::publishModule($sourcePath, 'my-module');
// 发布到: modules/MyModule/
```

## 菜单控制

### deleteAdminModuleMenu - 删除模块菜单

删除指定模块的所有菜单。

```php
Plugin::deleteAdminModuleMenu('Test\Test');
```

### disableAdminModuleMenu - 禁用菜单

```php
Plugin::disableAdminModuleMenu('Test\Test', 'UserController@index');
// 或批量禁用
Plugin::disableAdminModuleMenu('Test\Test', ['UserController@index', 'UserController@store']);
```

### enableAdminModuleMenu - 启用菜单

```php
Plugin::enableAdminModuleMenu('Test\Test', 'UserController@index');
```

## 资源相关

### publish - 发布资源

将目录从源位置复制到目标位置。

```php
Plugin::publish($from, $to);
```

### getPluginPath - 获取插件路径

```php
$path = Plugin::getPluginPath('my/plugin');
// 返回: /path/to/project/vendor/.../my/plugin
```

### all - 获取所有已安装插件

```php
$plugins = Plugin::all();
// 返回: ['my/plugin' => ['path' => '...'], ...]
```

### allRoutes - 获取所有插件路由文件

```php
$routes = Plugin::allRoutes();
// 返回: ['/path/to/plugin/routes/api.php', ...]
```

## 常用组合示例

### 安装时完整初始化

```php
public function afterInstall(array $context): void
{
    // 1. 执行数据库迁移
    Plugin::migrate($context['path'] . '/migrations');
    
    // 2. 填充初始数据
    Plugin::seed(\MyPlugin\Database\Seeders\InitSeeder::class);
    
    // 3. 创建菜单
    Plugin::createMenus([
        Plugin::createMenu('我的插件', '/my-plugin', $context['namespace'], children: [
            Plugin::createMenu('首页', 'index', $context['namespace'],
                controller: 'IndexController',
                controllerMethod: 'index',
                type: 2,
                component: Plugin::view('my/plugin', 'index')
            )
        ])
    ]);
}
```

### 卸载时清理

```php
public function afterUninstall(array $context): void
{
    // 删除菜单
    Plugin::deleteAdminModuleMenu($context['namespace']);
    
    // 删除已发布的视图
    Plugin::deleteView('my-plugin');
}
```

## 方法速查表

| 方法 | 用途 |
|------|------|
| `createMenus()` | 批量创建菜单 |
| `createMenu()` | 构建菜单数据 |
| `view()` | 生成视图 URL |
| `render()` | 渲染 Vue 页面 |
| `migrate()` | 执行迁移 |
| `seed()` | 执行填充 |
| `publish()` | 发布资源 |
| `publishView()` | 发布视图 |
| `publishModule()` | 发布模块 |
| `registerModule()` | 注册模块 |
| `unregisterModule()` | 注销模块 |
| `deleteAdminModuleMenu()` | 删除菜单 |
| `getPluginPath()` | 获取插件路径 |
| `all()` | 获取所有插件 |
| `allRoutes()` | 获取所有路由 |