什么是Composer插件（Plugin）？如何开发一个？（高级教程）

Composer插件是通过实现PluginInterface并在activate()中订阅事件来扩展Composer行为的工具，本质为事件驱动+服务注册，需声明type为composer-plugin并指定入口类。

Composer 插件是运行在 Composer 生命周期中、能修改其行为的 PHP 包，不是用来被项目 require 的功能库，而是用来扩展或干预 Composer 自身逻辑的工具 —— 比如自动加载优化、包下载前校验、安装后执行脚本、甚至重写依赖解析规则。

插件的本质：事件驱动 + 服务注册

Composer 插件不是靠“被调用”工作的，而是通过实现 Composer\Plugin\PluginInterface，并在 activate() 方法中向 Composer 的事件分发器（EventDispatcher）订阅事件，比如：

• pre-autoload-dump：生成自动加载文件前
• post-install-cmd 或 post-update-cmd：命令执行完成后
• pre-package-install：某个包真正下载前（可取消/替换）
• init：Composer 初始化时（适合注册自定义命令）

插件本身必须声明为 "type": "composer-plugin"，并设置 "extra": {"class": "Your\\Plugin\\Class"} 指明入口类。Composer 会扫描已安装的包，自动激活所有符合规范的插件。

开发一个最小可用插件

假设你想在每次 composer install 后打印一行带时间戳的提示：

1. 新建目录 my-company/composer-timestamp-plugin
2. 写 src/TimestampPlugin.php：

namespace MyCompany\Composer;

use Composer\Composer;
use Composer\IO\IOInterface;
use Composer\Plugin\PluginInterface;
use Composer\EventDispatcher\EventSubscriberInterface;
use Composer\Script\ScriptEvents;

class TimestampPlugin implements PluginInterface, EventSubscriberInterface
{
    private $io;

    public function activate(Composer $composer, IOInterface $io)
    {
        $this->io = $io;
    }

    public static function getSubscribedEvents()
    {
        return [
            ScriptEvents::POST_INSTALL_CMD => 'onPostInstall',
            ScriptEvents::POST_UPDATE_CMD   => 'onPostUpdate',
        ];
    }

    public function onPostInstall()
    {
        $this->io->write("✅ Install completed at " . date('Y-m-d H:i:s'));
    }

    public function onPostUpdate()
    {
        $this->io->write("? Update completed at " . date('Y-m-d H:i:s'));
    }
}

再写 composer.json：

{
  "name": "my-company/composer-timestamp-plugin",
  "type": "composer-plugin",
  "autoload": {
    "psr-4": { "MyCompany\\Composer\\": "src/" }
  },
  "require": {
    "composer-plugin-api": "^2.0"
  },
  "extra": {
    "class": "MyCompany\\Composer\\TimestampPlugin"
  }
}

然后在目标项目中运行：composer require my-company/composer-timestamp-plugin --dev，插件即生效。

进阶能力：操作包、修改下载行为、注入命令

真正强大的插件往往不止监听事件，还会主动介入核心流程：

• 通过 $composer->getPackage() 获取当前项目根包，读写 extra 配置
• 监听 pre-package-install 事件，调用 $event->setOperation(new NullOperation()) 可跳过安装某个包
• 使用 $composer->getInstallationManager()->addInstaller() 注册自定义安装器（如支持 `.zip` 发布包或私有协议）
• 在 activate() 中调用 $composer->getCommandLoader()->addCommand(...) 注入新命令（需继承 Symfony\Component\Console\Command\Command）

注意：从 Composer 2.0 起，插件不能直接访问 Composer\Package\PackageInterface 的私有属性，必须用 getter；且所有 I/O 必须通过 $io 实例，不可用 echo 或 var_dump。

调试与发布注意事项

插件出问题常表现为“完全不触发”，原因多为：

• 未正确声明 "type": "composer-plugin"，导致 Composer 忽略
• PSR-4 自动加载路径错误，类根本没被找到（检查 vendor/composer/autoload_psr4.php）
• PHP 版本或 composer-plugin-api 版本不匹配（Composer 2.x 对应 ^2.0，1.x 对应 ^1.0）
• 事件名拼写错误（如 post-update-cmd ≠ post-update-cmds）

发布前建议：在 tests/ 下写 PHPUnit 测试，模拟 Composer 和 IOInterface 实例验证事件响应；同时提供清晰的 README.md，说明支持的 Composer 版本和典型使用场景。

基本上就这些。插件机制不复杂但容易忽略细节，关键是理解它不是“功能模块”，而是 Composer 运行时的“钩子代理”。写得克制、职责单一、少侵入核心，才是稳定插件的起点。