Composer插件是通过实现PluginInterface并在activate()中订阅事件来扩展Composer行为的工具，本质为事件驱动+服务注册，需声明type为composer-plugin并指定入口类。
Composer 插件是运行在 Composer 生命周期中、能修改其行为的 PHP 包，不是用来被项目 require 的功能库，而是用来扩展或干预 Composer 自身逻辑的工具 —— 比如自动加载优化、包下载前校验、安装后执行脚本、甚至重写依赖解析规则。
插件的本质：事件驱动 + 服务注册
Composer 插件不是靠“被调用”工作的，而是通过实现 ComposerPluginPluginInterface，并在 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 后打印一行带时间戳的提示：
- 新建目录
my-company/composer-timestamp-plugin - 写
src/TimestampPlugin.php：
namespace MyCompanyComposer;
use ComposerComposer;
use ComposerIOIOInterface;
use ComposerPluginPluginInterface;
use ComposerEventDispatcherEventSubscriberInterface;
use ComposerScriptScriptEvents;
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，插件即生效。
使用约定式提交（Conventional Commits）生成标准化的 Git 提交信息。适用于以下场景： (1) 暂存更改时需要提交信息； (2) 审查 diff 时希望获得结构化摘要； (3) 编写 PR 描述或变更日志（changelog）条目； (4) 用户明确要求“为本次更改编写提交信息”。 该功能会分析已暂存/未暂存的 diff，并生成按类型（type）划分范围的提交信息。
进阶能力：操作包、修改下载行为、注入命令
真正强大的插件往往不止监听事件，还会主动介入核心流程：
- 通过
$composer->getPackage()获取当前项目根包，读写extra配置 - 监听
pre-package-install事件，调用$event->setOperation(new NullOperation())可跳过安装某个包 - 使用
$composer->getInstallationManager()->addInstaller()注册自定义安装器（如支持 `.zip` 发布包或私有协议） - 在
activate()中调用$composer->getCommandLoader()->addCommand(...)注入新命令（需继承SymfonyComponentConsoleCommandCommand）
注意：从 Composer 2.0 起，插件不能直接访问 ComposerPackagePackageInterface 的私有属性，必须用 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 运行时的“钩子代理”。写得克制、职责单一、少侵入核心，才是稳定插件的起点。
