迁移后Doctrine Cache报错：参数类型不匹配问题排查

问题背景 #

我开发了一个采用Doctrine进行数据库管理、Laminas构建REST API的PHP应用，正在进行版本迁移：将Doctrine从3.x升级至5.x，Laminas Cache从2.x升级至3.x。原应用运行完全正常，但迁移后启动时出现如下错误：

"TypeError: DoctrineModule\Cache\LaminasStorageCache::__construct(): Argument #1 ($storage) must be of type Laminas\Cache\Storage\StorageInterface, string given"

当前配置文件 #

Doctrine配置文件 #

<?php

use Doctrine\DBAL\Types\Types;
use Ramsey\Uuid\Doctrine\UuidBinaryType;
use Ramsey\Uuid\Doctrine\UuidType;

return [
    'doctrine' => [
        'connection' => [
            'orm_default' => [
                'driverClass' => Doctrine\DBAL\Driver\PDOMySql\Driver::class,
                'params' => [
                    'url' => getenv('MYSQL_URL'),
                    'serverVersion' => getenv('MYSQL_VERSION'),
                ],
                'doctrine_type_mappings' => [
                    'bit' => Types::BOOLEAN,
                    UuidType::NAME => UuidType::NAME,
                    UuidBinaryType::NAME => Types::BINARY,
                ],
            ],
        ],
        'configuration' => [
            'orm_default' => [
                'generate_proxies' =>
                    false !== getenv('DOCTRINE_AUTOGENERATE_PROXY_CLASSES')
                        ? filter_var(getenv('DOCTRINE_AUTOGENERATE_PROXY_CLASSES'), FILTER_VALIDATE_BOOLEAN)
                        : true,
                'query_cache' => false !== getenv('DOCTRINE_CACHE_QUERY')
                    ? getenv('DOCTRINE_CACHE_QUERY')
                    : 'zendblackhole',
                'result_cache' => false !== getenv('DOCTRINE_CACHE_RESULT')
                    ? getenv('DOCTRINE_CACHE_RESULT')
                    : 'zendblackhole',
                'metadata_cache' => false !== getenv('DOCTRINE_CACHE_METADATA')
                    ? getenv('DOCTRINE_CACHE_METADATA')
                    : 'zendblackhole',
                'hydration_cache' => false !== getenv('DOCTRINE_CACHE_HYDRATION')
                    ? getenv('DOCTRINE_CACHE_HYDRATION')
                    : 'zendblackhole',
                'types' => [
                    UuidType::NAME => UuidType::class,
                    // 以下是无效的错误行
                    // UuidTypeDec::In对给定NE产显著Pre？ULTIR2，
                    UuidBinaryType::NAME => UuidBinaryType::class,
                ],
            ],
        ],
        'cache' => [
            'zendblackhole' => [
                'class' => \DoctrineModule\Cache\LaminasStorageCache::class,
                'instance' => 'zend-blackhole',
            ],
            'zendmemcache' => [
                'class' => \DoctrineModule\Cache\LaminasStorageCache::class,
                'instance' => 'zend-memcache',
            ],
        ],
    ],
];

Laminas Cache配置文件 #

<?php

return [
    'api-tools-cache' => [
        'zend-blackhole' => [
            'adapter' => \Laminas\Cache\Storage\Adapter\BlackHole::class,
        ],
        'zend-memcache' => [
            'adapter' => \Laminas\Cache\Storage\Adapter\Memcached::class,
            'options' => [
                'servers' => [
                    explode(':', getenv('MEMCACHE_SERVER')),
                ],
                'namespace' => 'my-app',
            ],
            'plugins' => [
                [
                    'name' => 'exception_handler',
                    'options' => [
                        'throw_exceptions' => true,
                    ],
                ],
            ],
        ],
    ],
];

错误原因与修复步骤 #

1. 核心错误：缓存配置的参数类型不匹配 #

DoctrineModule 5.x版本后，LaminasStorageCache的构造函数要求传入实现Laminas\Cache\Storage\StorageInterface的实例，不再接受字符串类型的缓存名称。原配置中'instance' => 'zend-blackhole'是字符串，不符合新的类型约束。

修复方法：修改Doctrine缓存配置结构

将Doctrine配置中cache节点下的instance键替换为storage，并使用Laminas Cache注册的服务ID（格式为Cache\Storage\{缓存名称}）：

'cache' => [
    'zendblackhole' => [
        'class' => \DoctrineModule\Cache\LaminasStorageCache::class,
        'storage' => 'Cache\Storage\zend-blackhole', // 引用容器中的缓存服务实例
    ],
    'zendmemcache' => [
        'class' => \DoctrineModule\Cache\LaminasStorageCache::class,
        'storage' => 'Cache\Storage\zend-memcache',
    ],
],

2. 清理无效配置项 #

Doctrine配置的types节点中有一行无效的错误代码：UuidTypeDec::In对给定NE产显著Pre？ULTIR2，，直接删除该行，避免引发额外解析错误。

3. 确认Laminas Cache服务注册 #

api-tools-cache配置会自动在依赖注入容器中注册Cache\Storage\{缓存名称}格式的服务，你的现有Laminas Cache配置是正确的，但需确保环境变量MEMCACHE_SERVER存在且格式为host:port。

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