pre-file-download事件在Composer下载包文件前触发，可用于修改请求头、添加认证、替换镜像源或记录日志；通过composer.json的scripts配置或插件实现监听，典型场景包括为私有仓库添加Token、使用内部代理或监控下载行为；该事件作用于RemoteFilesystem实例，不影响元数据解析，适用于企业级定制需求。
Composer 的 "pre-file-download" 事件是一个钩子（Hook），它在 Composer 下载任何包文件（如 ZIP、TAR 等压缩包）之前触发。你可以利用这个事件执行自定义逻辑，比如修改下载地址、设置代理、添加认证头、记录日志，甚至替换源。
作用场景
这个事件的主要用途是让你在实际发起 HTTP 请求下载包前，对请求进行干预或调整。常见使用包括：
- 为私有仓库添加身份认证信息（如 Bearer Token 或 Basic Auth）
- 将默认的 GitHub 下载链接替换为内部镜像源
- 通过企业代理配置自定义 HTTP 头或客户端选项
- 监控和记录所有包的下载行为
如何使用 pre-file-download
你需要注册一个事件监听器，通常在项目的 composer.json 中通过脚本（scripts）配置，或者在自定义插件中实现。
示例：在 composer.json 中注册一个类来监听该事件：
{
"scripts": {
"pre-file-download": "MyDownloader::onPreFileDownload"
}
}
对应的 PHP 类需要实现静态方法：
MyDownloader.php<?php
class MyDownloader
{
public static function onPreFileDownload($event)
{
$downloadManager = $event->getComposer()->getDownloadManager();
$httpDownloader = $downloadManager->getDownloader('http');
// 修改 HTTP 请求选项，例如添加 Header
$httpDownloader->addOption('headers', ['Authorization: token YOUR_TOKEN']);
}
}
如果你开发的是 Composer 插件，可以通过订阅 PreFileDownloadEvent 来更精细地控制每个下载请求：
use Composer\Installer\PackageEvent;
use Composer\Plugin\PluginInterface;
use Composer\EventDispatcher\EventSubscriberInterface;
use Composer\Util\RemoteFilesystem;
class CustomDownloadPlugin implements PluginInterface, EventSubscriberInterface
{
public function activate(Composer $composer, IO $io)
{
// 注册事件监听
}
public static function getSubscribedEvents()
{
return ['pre-file-download' => 'onPreFileDownload'];
}
public function onPreFileDownload(\Composer\Script\Event $event)
{
$request = $event->getContext(); // 获取当前 RemoteFilesystem 实例
if ($request instanceof RemoteFilesystem) {
$request->addOptions(['headers' => ['User-Agent: MyCompany-Proxy']]);
}
}
}
关键点说明
-
事件上下文：事件的
getContext()方法返回正在使用的RemoteFilesystem实例，你可以通过它修改请求参数。 -
不影响包元数据：此事件仅针对“文件下载”阶段，不涉及
composer.json的读取或版本解析。 - 适用于高级定制：普通项目一般不需要使用，多用于企业级环境、私有组件分发或安全合规需求。
基本上就这些。合理使用 pre-file-download 能帮助你在不修改核心代码的前提下，灵活控制依赖包的获取方式。
