Composer如何启用插件功能 Composer扩展功能开发指南

Composer 2.2+ 默认禁用插件，必须在项目根目录 composer.json 根级配置 allow-plugins 为字符串数组（如 ["symfony/flex"]），大小写敏感且不可通配；全局插件需配置 ~/.composer/config.json 中的 config.allow-plugins。

Composer 2.2+ 必须显式允许插件，否则直接报错

从 Composer 2.2 版本开始，安全策略来了个“急转弯”：所有被标记为 type: "composer-plugin" 的包，默认都会被禁用。如果你没做任何配置就直接运行 composer install，大概率会看到一个中断提示："Plugin installation is disabled"。这可不是什么配置疏忽，而是一项强制性的安全策略——你必须主动在项目根目录的 composer.json 里，明确声明 allow-plugins。

这里有几个常见的“坑”。首先，有人图省事，直接写 "allow-plugins": true。这相当于放弃了所有安全控制，并不推荐。更棘手的是漏掉了关键插件，比如负责 Symfony 项目自动配置的 symfony/flex，或者 PHPStan 的扩展安装器 phpstan/extension-installer。一旦漏掉，前者会导致那些方便的“recipe”配置不生效，后者则可能让静态分析工具无法正常集成。

• 记住，allow-plugins 必须写在 composer.json 的根级别，放在 config 或 extra 这些节点下面可不行。
• 它的值必须是一个字符串数组，包名大小写敏感，而且不支持通配符。举个例子，你得写成完整的 "dealerdirect/phpcodesniffer-composer-installer"，光写 "phpcodesniffer-composer-installer" 是无效的。
• 如果你是通过 composer global require 安装的全局插件，那还得在全局配置里（通常是 ~/.composer/config.json）设置 config.allow-plugins。

插件没加载？先确认它是否真被识别为插件

有时候，你觉得插件装好了，但它就是没动静。第一步，别急着怀疑人生，先验证一下 Composer 到底有没有把它当成一个“插件”。运行 composer show vendor/package-name，仔细看看输出信息里有没有 types : composer-plugin 这一行。如果没有，那问题就清楚了——Composer 压根没把它当插件看，哪怕这个包的代码里规规矩矩地写了 Plugin 类和 activate() 方法，也是白搭。

哪些包容易被误认为是插件呢？比如那些只提供二进制命令的工具（像 phpunit/phpunit）、包含一些辅助函数的库，或者最关键的一点——作者在它的 composer.json 里没有声明 "type": "composer-plugin"。这类包，你 require 之后，不会触发任何插件生命周期。

• 一个包要成为插件，其自身的 composer.json 里必须包含 "type": "composer-plugin"。这个是由包作者定义的，使用者没法通过修改来“变”出一个插件。
• 在你的项目 composer.json 中，这个包必须被列在 require 或 require-dev 里，并且你已经执行过 composer install 或针对它的 composer update vendor/package-name。
• 如果插件来自私有 Git 仓库，别忘了在 repositories 里用 type: "vcs" 声明，并且确保仓库里有有效的 tag（例如 v1.0.0）。

插件类写了但 activate() 没执行？检查 autoload 和签名

好，现在包被识别为插件了，但它的 activate() 方法还是没被调用？这种情况往往更隐蔽。Composer 会静默跳过那些自动加载失败、或者方法签名不匹配的插件——你不会收到任何报错，只会发现插件好像“没装一样”。

有个非常实用的验证技巧：在插件类的 activate() 方法开头，加一行简单的日志代码，比如 file_put_contents('/tmp/plugin-activated', 'yes', FILE_APPEND)。然后运行 composer install -v，看看这个文件有没有被创建。如果文件出现了，说明插件确实被激活了，问题可能出在别处。

• 如果插件的 composer.json 里指定了 extra.class 字段，那么它必须指向完整的命名空间类名，例如 "MyVendor\MyPlugin\MyPlugin"。用短名或者相对路径是行不通的。
• 插件类必须能被正确自动加载。检查一下项目的 autoload["psr-4"] 配置是否覆盖了该类的路径。修改完自动加载配置后，务必运行 composer dump-autoload -o 来优化加载器。
• activate() 的方法签名必须严格匹配：public function activate(Composer\Composer $composer, Composer\IO\IOInterface $io)。参数的类型和顺序，错一个字符都会导致方法不被调用。

命令没出现、事件不触发？不是插件没加载，是没暴露功能

这里有个关键概念需要厘清：插件加载成功，并不等于它的自定义命令就可用，也不等于它注册的事件监听器会生效。这是两件解耦的事情。activate() 只是插件的入口，之后你需要手动去注册命令和事件监听器。

举个例子，你想让 composer my-command 这个命令可用，仅仅实现 PluginInterface 是不够的。你必须在插件类里重写 getCommands() 方法，并且返回一个由 Composer\Command\Command 实例组成的数组。同理，如果你想监听 post-install-cmd 这样的事件，就需要在 activate() 方法内部，调用类似 $composer->getEventDispatcher()->addListener('post-install-cmd', ...) 的代码来注册。

• 运行 composer list，看看你的自定义命令有没有出现在列表里。如果没有，那很可能是 getCommands() 方法没有返回有效的对象，或者返回的对象没有继承 Composer\Command\BaseCommand。
• 注册事件时，事件名必须是纯字符串，比如 "post-autoload-dump"。不能直接使用常量（如 ScriptEvents::POST_AUTOLOAD_DUMP），而且大小写、下划线都不能写错。
• 在事件监听器的回调函数里，尽量避免直接抛出（throw）异常。因为这会导致整个 composer install 过程以错误退出，用户可能根本看不到你精心准备的提示信息。

最后，还有一个真正容易被忽略的点：插件是否生效，只取决于它是否出现在你当前执行 composer 命令的那个项目的 composer.json 中，并且当前执行的命令是否触发了插件的注册阶段。在其他任何位置 require 这个插件，都是无效的。