Composer插件通过实现PluginInterface并在composer.json中声明，可在生命周期事件中注入自定义逻辑；最小结构包含声明文件、主类和autoload配置。

Composer 插件是 PHP 项目中增强依赖管理能力的重要方式，它允许你在 Composer 的生命周期中注入自定义逻辑，比如自动加载优化、包发布前校验、镜像源切换、自定义安装器等。关键在于理解插件的触发时机（如 post-install-cmd、pre-autoload-dump）和正确实现 Composer\Plugin\PluginInterface。

插件基础结构：从一个最小可运行示例开始

创建一个最简插件，只需三部分：composer.json 声明、主类实现 PluginInterface、以及 autoload 配置。

• 新建目录 my-composer-plugin，在其中创建 composer.json：

{
  "name": "myorg/my-composer-plugin",
  "type": "composer-plugin",
  "require": {
    "composer-plugin-api": "^2.0"
  },
  "autoload": {
    "psr-4": {
      "MyOrg\\ComposerPlugin\\": "src/"
    }
  },
  "extra": {
    "class": "MyOrg\\ComposerPlugin\\MyPlugin"
  }
}


  
在 src/MyPlugin.php 中实现插件主体：


 'onPostInstall',
        ];
    }

    public function onPostInstall($event)
    {
        $io = $event->getIO();
        $io->write('✅ 自定义插件：post-install 完成，正在生成 API 文档...');
        // 这里可调用 phpdocumentor、swagger 等工具
    }
}



在项目根目录的 composer.json 中引入该插件：


"require-dev": {
  "myorg/my-composer-plugin": "dev-main"
},
"repositories": [{
  "type": "path",
  "url": "../my-composer-plugin"
}]


执行 composer install 后即可看到插件输出。

实用场景：自动替换包源 + 验证包完整性
很多团队需要将公共包（如 monolog/monolog）重定向到私有仓库，并在校验失败时中断安装。这可通过监听 PRE_POOL_CREATE 和 POST_PACKAGE_INSTALL 实现。

在插件中监听 PrePoolCreateEvent 修改仓库配置：


use Composer\Plugin\Capability\CommandProvider;
use Composer\EventDispatcher\PrePoolCreateEvent;
use Composer\Repository\CompositeRepository;
use Composer\Repository\PlatformRepository;
use Composer\Repository\InstalledRepository;
use Composer\Repository\RepoRepository;

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

public static function getSubscribedEvents()
{
    return [
        'pre-pool-create' => 'onPrePoolCreate',
        'post-package-install' => 'onPostPackageInstall',
    ];
}

public function onPrePoolCreate(PrePoolCreateEvent $event)
{
    $packages = $event->getPackages();
    foreach ($packages as $package) {
        if ($package->getName() === 'monolog/monolog') {
            // 强制使用内部镜像
            $config = $this->composer->getConfig();
            $config->merge(['repositories' => [
                ['type' => 'composer', 'url' => 'https://pkg.mycompany.com']
            ]]);
        }
    }
}

public function onPostPackageInstall($event)
{
    $package = $event->getOperation()->getPackage();
    $dist = $package->getDist();
    if ($dist && !empty($dist['shasum'])) {
        $zipPath = $event->getComposer()->getInstallationManager()
            ->getInstaller('library')
            ->getInstallPath($package);
        $downloadedZip = $zipPath . '/'. basename($dist['url']);
        if (file_exists($downloadedZip) && sha1_file($downloadedZip) !== $dist['shasum']) {
            $this->io->writeError('❌ 校验失败：' . $package->getName() . ' SHA1 不匹配');
            exit(1);
        }
    }
}



高级技巧：自定义命令 + 集成 Laravel Mix 构建流程
插件可注册新命令（需实现 CommandProvider），例如添加 composer build:assets 来触发前端资源构建。

让插件同时实现 CommandProvider 接口：


use Composer\Plugin\Capability\CommandProvider as CommandProviderCapability;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Command\Command;

class MyPlugin implements PluginInterface, EventSubscriberInterface, CommandProviderCapability
{
    public function getCommands()
    {
        return [new BuildAssetsCommand()];
    }
}

class BuildAssetsCommand extends Command
{
    protected function configure()
    {
        $this->setName('build:assets')
             ->setDescription('Run Laravel Mix to compile frontend assets');
    }

    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $result = shell_exec('cd ./resources && npm run production 2>&1');
        $output->writeln($result ?: '✨ 构建完成');
        return 0;
    }
}


安装插件后，直接运行 composer build:assets 即可触发前端编译，无需额外脚本或 Makefile。

调试与发布建议
插件开发中容易踩坑，推荐以下实践：

使用 COMPOSER_MEMORY_LIMIT=-1 composer -vvv install 查看详细日志和插件加载顺序
  
插件类必须声明 extra.class，且命名空间路径需与 autoload 严格一致
  
避免在插件中修改全局 composer.json，应通过 $composer->getPackage() 获取当前项目配置
  
发布前用 composer validate 检查插件包的 composer.json 是否符合规范
  
私有插件推荐用 type: composer-plugin + path 或 artifact 仓库管理，而非直接 push 到 Packagist

不复杂但容易忽略：插件只在 composer install/update 时激活，不会影响已安装包的运行时行为；所有扩展都应保持幂等性，避免重复执行导致异常。