插件生命周期钩子

钩子（Hook）是插件与 CatchAdmin 系统交互的桥梁，让你可以在插件安装、更新、卸载的各个阶段执行自定义逻辑。

钩子文件

每个插件根目录下都有一个 hook.php 文件，包含一个 Hook 类：

<?php

class Hook
{
    public function beforeInstall(array $context): void { }
    
    public function afterInstall(array $context): void { }
    
    public function beforeUpdate(array $context): void { }
    
    public function afterUpdate(array $context): void { }
    
    public function beforeUninstall(array $context): void { }
    
    public function afterUninstall(array $context): void { }
}

钩子方法一览

钩子方法	触发时机	常见用途
beforeInstall	安装前	检查安装条件、验证环境依赖
afterInstall	安装后	创建菜单、初始化数据、发布配置
beforeUpdate	更新前	备份数据、记录旧版本信息
afterUpdate	更新后	执行数据迁移、更新缓存
beforeUninstall	卸载前	备份用户数据、确认卸载
afterUninstall	卸载后	清理菜单、删除相关数据

Context 参数

每个钩子方法都会接收一个 $context 数组，包含插件的基本信息：

$context = [
    'name'      => 'test/test',           // 包名
    'version'   => '1.0.0',               // 版本号
    'path'      => 'vendor/.../test',     // 安装路径
    'namespace' => 'Test\Test',           // 根命名空间
];

常见应用场景

1. 安装时自动创建菜单

public function afterInstall(array $context): void
{
    Plugin::createMenus([
        Plugin::createMenu('我的插件', '/my-plugin', $context['namespace'], children: [
            Plugin::createMenu('用户管理', 'users', $context['namespace'],
                controller: 'UserController',
                controllerMethod: 'index',
                type: 2,
                component: Plugin::view('my/plugin', 'users.index')
            )
        ])
    ]);
}

2. 卸载时清理菜单

public function afterUninstall(array $context): void
{
    // 删除该插件创建的所有菜单
    Permissions::where('module', $context['namespace'])->delete();
}

3. 安装前检查条件

public function beforeInstall(array $context): void
{
    // 检查 PHP 版本
    if (version_compare(PHP_VERSION, '8.1', '<')) {
        throw new \RuntimeException('此插件需要 PHP 8.1 或更高版本');
    }
    
    // 检查依赖扩展
    if (!extension_loaded('redis')) {
        throw new \RuntimeException('此插件需要 Redis 扩展');
    }
}

4. 安装后初始化数据

public function afterInstall(array $context): void
{
    // 执行数据库迁移
    Artisan::call('migrate', [
        '--path' => $context['path'] . '/migrations'
    ]);
    
    // 发布配置文件
    Artisan::call('vendor:publish', [
        '--tag' => 'my-plugin-config'
    ]);
    
    // 初始化默认数据
    \DB::table('settings')->insert([
        'key' => 'my_plugin_enabled',
        'value' => 'true'
    ]);
}

5. 更新前备份数据

public function beforeUpdate(array $context): void
{
    // 备份配置
    $config = config('my-plugin');
    file_put_contents(
        storage_path('backups/my-plugin-config.json'),
        json_encode($config)
    );
}

6. 卸载前确认并备份

public function beforeUninstall(array $context): void
{
    // 导出用户数据
    $users = \DB::table('my_plugin_users')->get();
    file_put_contents(
        storage_path('backups/my-plugin-users.json'),
        json_encode($users)
    );
}

注意事项

⚠️ 重要提示

1. 钩子中可以使用 Laravel 功能：包括 Eloquent、Artisan、配置、日志等
2. beforeInstall 抛出异常可阻止安装：用于环境检查
3. afterUninstall 时包文件仍存在：可以访问插件的静态资源
4. 钩子方法是实例方法：不是静态方法

下一步

• 了解如何开发完整插件：插件开发实战
• 从零开始创建插件：快速入门