设置和使用插件

概述

你可能需要改变和扩展 Composer 加入自定义的功能。例如：如果你的环境对 Composer 的行为有特殊要求，而这并不适用于普通用户。又或者，你想使用 Composer 完成某些事情，而又不希望对普通用户造成影响。

在这些情况下，你可以考虑创建一个插件来处理特定的逻辑。

创建一个插件

一个插件就是一个普通的 Composer 资源包，插件的主要代码都位于这个包中，并且还可以依赖更多其它的资源包。

插件包

插件包内的文件和普通资源包相同，但必须满足下列要求：

  • type 属性必须是 composer-plugin。
  • extra 属性必须包含一个元素 class，它定义了插件类的名称（包含命名空间）。如果一个包中含有多个插件，则可以使用数组来定义类名。

此外，你必须 require 一个特殊的资源包 composer-plugin-api，定义与你的插件相兼容的 composer plugin API 版本。目前 composer plugin API 的版本为1.0.0。

实例：

  1. {
  2.     "name": "my/plugin-package",
  3.     "type": "composer-plugin",
  4.     "require": {
  5.         "composer-plugin-api": "1.0.0"
  6.     }
  7. }

插件类

每一个插件都必须提供一个实现了 Composer\Plugin\PluginInterface 接口的类。类中的 activate() 方法在插件载入后被调用，并接收两个类的实例：Composer\Composer 和 Composer\IO\IOInterface。使用这两个对象可以读取所有的配置，操作所有的内部对象和状态。

实例：

  1. <?php
  3. namespace phpDocumentor\Composer;
  5. use Composer\Composer;
  6. use Composer\IO\IOInterface;
  7. use Composer\Plugin\PluginInterface;
  9. class TemplateInstallerPlugin implements PluginInterface
  10. {
  11.     public function activate(Composer $composer, IOInterface $io)
  12.     {
  13.         $installer = new TemplateInstaller($io, $composer);
  14.         $composer->getInstallationManager()->addInstaller($installer);
  15.     }
  16. }

事件处理程序

此外，插件还可以实现 Composer\EventDispatcher\EventSubscriberInterface 接口，为了在插件载入后自动注册事件处理程序到 EventDispatcher。

插件可用事件如下：

  • COMMAND 在载入插件的所有命令前被调用。它为你提供了访问程序输入输出的对象。
  • PRE_FILE_DOWNLOAD 在文件下载前被触发，它允许你在下载前根据目标 URL 操作 RemoteFilesystem 对象。

一个插件也可以订阅 脚本事件。

实例：

  1. <?php
  3. namespace Naderman\Composer\AWS;
  5. use Composer\Composer;
  6. use Composer\EventDispatcher\EventSubscriberInterface;
  7. use Composer\IO\IOInterface;
  8. use Composer\Plugin\PluginInterface;
  9. use Composer\Plugin\PluginEvents;
  10. use Composer\Plugin\PreFileDownloadEvent;
  12. class AwsPlugin implements PluginInterface, EventSubscriberInterface
  13. {
  14.     protected $composer;
  15.     protected $io;
  17.     public function activate(Composer $composer, IOInterface $io)
  18.     {
  19.         $this->composer = $composer;
  20.         $this->io = $io;
  21.     }
  23.     public static function getSubscribedEvents()
  24.     {
  25.         return array(
  26.             PluginEvents::PRE_FILE_DOWNLOAD => array(
  27.                 array('onPreFileDownload', 0)
  28.             ),
  29.         );
  30.     }
  32.     public function onPreFileDownload(PreFileDownloadEvent $event)
  33.     {
  34.         $protocol = parse_url($event->getProcessedUrl(), PHP_URL_SCHEME);
  36.         if ($protocol === 's3') {
  37.             $awsClient = new AwsClient($this->io, $this->composer->getConfig());
  38.             $s3RemoteFilesystem = new S3RemoteFilesystem($this->io, $event->getRemoteFilesystem()->getOptions(), $awsClient);
  39.             $event->setRemoteFilesystem($s3RemoteFilesystem);
  40.         }
  41.     }
  42. }

使用插件

插件包是优先被安装和加载的，在 Composer 启动时，如果在已安装资源包的当前项目列表中被找到，它们将被自动加载。此外，所有的插件包将被安装在 COMPOSER_HOME 目录，以便在 Composer 全局命令前载入，在操作本地项目前插件就已经被载入。

你可以通过 --no-plugins 选项让 composer 的命令禁用所有已经安装的插件。这或许是特别有用的，如果任何插件会导致错误，而你想要升级或卸载它。