Symfony6/Pimcore：如何通过自定义Bundle覆盖原生Flysystem配置

数据老陈

2026-7-2

稳定覆盖Pimcore原生Flysystem配置，替换为Azure存储适配器

问题背景

我开发了一个Symfony Bundle，用于让Pimcore系统通过Flysystem读写Azure存储文件。Pimcore自带Flysystem默认配置（对应11.x版本CoreBundle下的flysystem.yaml），需要让自定义Bundle的配置稳定覆盖原生配置，但目前将自定义config.yaml放在config/pimcore目录下时，覆盖效果不稳定：

有时文件会写入本地文件系统而非Azure
执行bin/console debug:container flysystem或bin/console debug:config flysystem时，时而加载原生LocalFilesystemAdapter，时而加载自定义TorqAzureBlobStorageAdapter

尝试用Compiler Pass替换适配器类时，出现参数错误：

TorqIT\FlysystemAzureBundle\TorqAzureBlobStorageAdapter::__construct(): Argument #1 ($client) must be of type MicrosoftAzure\Storage\Blob\BlobRestProxy, string given

调试发现容器传递的是LocalFilesystemAdapter的参数，尝试用setArgument覆盖但因加载顺序问题失效，现寻求稳定覆盖方案。

解决方案

方法一：利用Symfony配置优先级直接覆盖

Pimcore的Flysystem配置通过pimcore.flysystem节点定义，直接在自定义Bundle的配置文件（如config/packages/pimcore_flysystem_azure.yaml）中覆盖对应适配器配置，确保配置优先级高于原生配置。

示例配置

pimcore:
  flysystem:
    adapters:
      pimcore.asset.storage:
        adapter: 'torq_azure_blob_storage'
        options:
          client: '@azure_blob_client'
          container: '%env(AZURE_ASSET_CONTAINER)%'
      pimcore.document_static.storage:
        adapter: 'torq_azure_blob_storage'
        options:
          client: '@azure_blob_client'
          container: '%env(AZURE_DOCUMENT_CONTAINER)%'
      # 按需添加其他需要替换的适配器：thumbnail、version、recycle_bin等

注册自定义适配器类型

在Bundle的Dependency Injection扩展类（如DependencyInjection/TorqITFlysystemAzureExtension.php）中注册自定义Flysystem适配器类型：

public function load(array $configs, ContainerBuilder $container)
{
    $loader = new Loader\YamlFileLoader($container, new FileLocator(__DIR__.'/../Resources/config'));
    $loader->load('services.yaml');

    // 注册自定义适配器类型
    $flysystemExtension = $container->getExtension('flysystem');
    $flysystemExtension->registerAdapterFactory(
        'torq_azure_blob_storage',
        TorqAzureBlobStorageAdapterFactory::class
    );
}

确保Bundle加载顺序

在Bundle类中声明依赖PimcoreCoreBundle，保证自定义配置后加载覆盖原生配置：

public function getDependencies(): array
{
    return [Pimcore\CoreBundle\PimcoreCoreBundle::class];
}

方法二：Compiler Pass完整替换服务定义

之前的Compiler Pass仅修改服务类，未替换参数，需直接覆盖整个服务定义。

修改后的Compiler Pass

final class FlysystemAzurePass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
        $adapterMapping = [
            'flysystem.adapter.pimcore.asset.storage' => 'assets_adapter',
            'flysystem.adapter.pimcore.document_static.storage' => 'document_static_adapter',
            // 其他适配器映射
        ];

        foreach ($adapterMapping as $pimcoreServiceId => $customServiceId) {
            if (!$container->hasDefinition($pimcoreServiceId) || !$container->hasDefinition($customServiceId)) {
                continue;
            }

            // 克隆自定义适配器的完整定义，替换原生服务
            $customDefinition = clone $container->getDefinition($customServiceId);
            $container->setDefinition($pimcoreServiceId, $customDefinition);
        }
    }
}

配置自定义适配器服务

在services.yaml中正确配置自定义适配器的依赖参数：

services:
  azure_blob_client:
    class: MicrosoftAzure\Storage\Blob\BlobRestProxy
    factory: [MicrosoftAzure\Storage\Blob\BlobRestProxy, createBlobService]
    arguments: ['%env(AZURE_BLOB_CONNECTION_STRING)%']

  assets_adapter:
    class: TorqIT\FlysystemAzureBundle\TorqAzureBlobStorageAdapter
    arguments:
      - '@azure_blob_client'
      - '%env(AZURE_ASSET_CONTAINER)%'
    tags: ['flysystem.adapter']

设置Compiler Pass执行顺序

在Bundle的build方法中设置Pass优先级，确保在Pimcore原生Pass之后执行：

public function build(ContainerBuilder $container)
{
    parent::build($container);
    $container->addCompilerPass(new FlysystemAzurePass(), PassConfig::TYPE_BEFORE_OPTIMIZATION, -100);
}

方法三：利用Pimcore原生事件扩展点

通过监听Pimcore的pimcore.flysystem.adapter_config事件，动态替换适配器配置，兼容性更好。

事件监听器实现

final class FlysystemAzureAdapterListener
{
    public function __construct(private ContainerInterface $container) {}

    public function onAdapterConfig(AdapterConfigEvent $event): void
    {
        $targetAdapters = [
            'pimcore.asset.storage',
            'pimcore.document_static.storage',
            // 其他需要替换的适配器
        ];

        if (!in_array($event->getAdapterName(), $targetAdapters)) {
            return;
        }

        // 替换为自定义适配器配置
        $event->setAdapterConfig([
            'adapter' => 'torq_azure_blob_storage',
            'options' => [
                'client' => $this->container->get('azure_blob_client'),
                'container' => $_ENV['AZURE_ASSET_CONTAINER'],
            ],
        ]);
    }
}

注册监听器

在services.yaml中添加监听器标签：

services:
  TorqIT\FlysystemAzureBundle\EventListener\FlysystemAzureAdapterListener:
    arguments: ['@service_container']
    tags:
      - { name: kernel.event_listener, event: pimcore.flysystem.adapter_config, method: onAdapterConfig }

方案优先级建议

方法一（配置覆盖）：最符合Symfony和Pimcore设计规范，配置清晰，维护成本低
方法三（事件扩展）：利用Pimcore原生扩展点，避免容器加载顺序问题，兼容性更强
方法二（Compiler Pass）：作为兜底方案，适合复杂场景下的服务替换

内容的提问来源于stack exchange，提问作者sonofjack3