PHP composer.json 脚本钩子

本文目录导读：

1. 基本结构
2. 常用脚本钩子类型
3. 常用示例
4. 高级用法
5. 实际项目示例
6. 常用注意事项

在 PHP Composer 中，composer.json 的脚本钩子（Script Hooks）允许你在 Composer 执行特定操作时自动运行自定义脚本，以下是一个完整的指南：

基本结构

{
    "scripts": {
        "post-install-cmd": [
            "php bin/install.php",
            "My\\Namespace\\Scripts::postInstall"
        ],
        "post-update-cmd": "@php vendor/bin/phpunit"
    }
}

常用脚本钩子类型

生命周期事件（Lifecycle Events）

{
    "scripts": {
        "pre-install-cmd": "自定义命令",
        "post-install-cmd": "自定义命令",
        "pre-update-cmd": "自定义命令",
        "post-update-cmd": "自定义命令",
        "pre-status-cmd": "自定义命令",
        "post-status-cmd": "自定义命令",
        "pre-archive-cmd": "自定义命令",
        "post-archive-cmd": "自定义命令",
        "pre-autoload-dump": "自定义命令",
        "post-autoload-dump": "自定义命令",
        "pre-root-package-install": "自定义命令",
        "post-root-package-install": "自定义命令",
        "pre-package-install": "自定义命令",
        "post-package-install": "自定义命令",
        "pre-package-update": "自定义命令",
        "post-package-update": "自定义命令",
        "pre-package-uninstall": "自定义命令",
        "post-package-uninstall": "自定义命令"
    }
}

自定义脚本

{
    "scripts": {
        "custom-script": "php scripts/custom.php",
        "test": "phpunit"
    }
}

常用示例

数据库迁移 + 缓存清理

{
    "scripts": {
        "post-install-cmd": [
            "@php artisan migrate",
            "@php artisan cache:clear",
            "@php artisan config:cache"
        ],
        "post-update-cmd": [
            "@php artisan migrate",
            "@php artisan optimize"
        ]
    }
}

使用 @ 符号

{
    "scripts": {
        "post-autoload-dump": [
            "@php artisan package:discover",
            "@php artisan storage:link"
        ],
        "clear-cache": [
            "@php artisan cache:clear",
            "@php artisan view:clear",
            "@php artisan route:clear"
        ]
    }
}

条件执行（基于环境）

{
    "scripts": {
        "post-install-cmd": [
            "if [ \"$APP_ENV\" = \"production\" ]; then php artisan config:cache; fi"
        ]
    }
}

高级用法

事件类脚本

{
    "scripts": {
        "post-update-cmd": {
            "description": "更新后运行迁移",
            "class": "App\\Composer\\UpdateScripts"
        }
    }
}

对应 PHP 类：

<?php
namespace App\Composer;
class UpdateScripts
{
    public static function postUpdate()
    {
        // 执行迁移
        shell_exec('php artisan migrate');
        // 清理缓存
        shell_exec('php artisan cache:clear');
        echo "✔ 更新完成！\n";
    }
}

多环境配置

{
    "scripts": {
        "post-install-cmd": [
            "php bin/install.php",
            "Production\\Scripts::run"
        ],
        "post-install-playground-cmd": [
            "PHP playground 环境的话则运行此脚本"
        ],
        "post-install-development-cmd": [
            "PHP development 环境的话则运行此脚本"
        ]
    }
}

事件监听器（Event Listeners）

{
    "scripts": {
        "post-autoload-dump": "MyComposerPlugin::postAutoloadDump"
    },
    "extra": {
        "class": []
    }
}

实际项目示例

{
    "name": "my-application/app",
    "scripts": {
        "post-install-cmd": [
            "@php -r \"copy('.env.example', '.env');\"",
            "@php artisan key:generate",
            "@php artisan migrate --seed",
            "@php artisan storage:link"
        ],
        "post-update-cmd": [
            "@php artisan migrate",
            "@php artisan optimize:clear",
            "npm run build"
        ],
        "dev": [
            "@php artisan serve",
            "npm run dev"
        ],
        "test": [
            "@php vendor/bin/phpunit",
            "npm test"
        ],
        "deploy": [
            "@composer install --no-dev",
            "@php artisan migrate --force",
            "@php artisan config:cache",
            "@php artisan route:cache",
            "@php artisan view:cache",
            "@php artisan queue:restart"
        ]
    },
    "extra": {
        "scripts-descriptions": {
            "dev": "启动开发服务器和前端",
            "test": "运行测试",
            "deploy": "部署到生产环境"
        }
    }
}

常用注意事项

跨平台兼容

{
    "scripts": {
        "post-install-cmd": [
            "@php bin/post-install.php"
        ]
    }
}

错误处理

{
    "scripts": {
        "post-update-cmd": [
            "php artisan migrate --force || exit 1",
            "@php artisan cache:clear"
        ]
    }
}

使用 helper 方法

{
    "scripts": {
        "post-install-cmd": [
            "Composer\\Installer::run"
        ]
    }
}

调试脚本

# 查看脚本执行
composer run-script --list
# 跳过脚本
composer install --no-scripts
# 跳过特定脚本
composer install --no-scripts --ignore-platform-reqs
# 详细输出
composer install -vvv

这些钩子让你可以在 Composer 生命周期中执行自动化任务，使项目安装、部署和更新过程更加智能和自动化，合理使用可以大大提升开发效率。