Symfony集成Doctrine MongoDB ODM构造函数参数不足500错误排查

在Docker（v20.10.22）环境的Ubuntu实例（5.15.0-60-generic）中，向运行的Symfony（v6.1.12，PHP8.2.1）应用的API Platform接口发送类似http://localhost/api/posts?limit=20的请求时，持续返回500服务器错误，错误提示：

Too few arguments to function Doctrine\ODM\MongoDB\PersistentCollection::__construct(), 0 passed in /var/www/html/vendor/doctrine/mongodb-odm/lib/Doctrine/ODM/MongoDB/PersistentCollection/DefaultPersistentCollectionFactory.php on line 16 and exactly 3 expected

所有针对该API Platform的请求在Ubuntu 22.04.1 LTS的Docker容器中均会触发此错误。项目Composer依赖中相关包版本如下：

composer show | grep 'symfony\|doctrine'
dama/doctrine-test-bundle            v6.7.5    Symfony bundle to isolate doctrine database tests and improve test performance
doctrine/annotations                 1.14.3    Docblock Annotations Parser
doctrine/cache                       2.2.0     PHP Doctrine Cache library is a popular cache implementation that supports many different drivers suc...
doctrine/collections                 1.8.0     PHP Doctrine Collections library that adds additional functionality on top of PHP arrays.
doctrine/common                      3.4.3     PHP Doctrine Common project is a library that provides additional functionality that other Doctrine p...
doctrine/data-fixtures               1.6.3     Data Fixtures for all Doctrine Object Managers
doctrine/dbal                        3.6.0     Powerful PHP database abstraction layer (DBAL) with many features for database schema introspection a...
doctrine/deprecations                v1.0.0    A small layer on top of trigger_error(E_USER_DEPRECATED) or PSR-3 logging with options to disable all...
doctrine/doctrine-bundle             2.8.3     Symfony DoctrineBundle
doctrine/doctrine-fixtures-bundle    3.4.2     Symfony DoctrineFixturesBundle
doctrine/doctrine-migrations-bundle  3.2.2     Symfony DoctrineMigrationsBundle
doctrine/event-manager               1.2.0     The Doctrine Event Manager is a simple PHP event system that was built to be used with the various Do...
doctrine/inflector                   2.0.6     PHP Doctrine Inflector is a small library that can perform string manipulations with regard to upper/...
doctrine/instantiator                1.5.0     A small, lightweight utility to instantiate objects in PHP without invoking their constructors
doctrine/lexer                       2.1.0     PHP Doctrine Lexer parser library that can be used in Top-Down, Recursive Descent Parsers.
doctrine/migrations                  3.6.0     PHP Doctrine Migrations project offer additional functionality on top of the database abstraction lay...
doctrine/mongodb-odm                 2.4.3     PHP Doctrine MongoDB Object Document Mapper (ODM) provides transparent persistence for PHP objects to...
doctrine/mongodb-odm-bundle          4.5.2     Symfony Doctrine MongoDB Bundle
doctrine/orm                         2.14.1    Object-Relational-Mapper for PHP
doctrine/persistence                 3.1.4     The Doctrine Persistence project is a set of shared interfaces and functionality that the different D...
doctrine/sql-formatter               1.1.3     a PHP SQL highlighting library
friendsofsymfony/elastica-bundle     v6.2.0    Elasticsearch PHP integration for your Symfony project using Elastica
gedmo/doctrine-extensions            v3.11.1   Doctrine behavioral extensions
stof/doctrine-extensions-bundle      v1.7.1    Integration of the gedmo/doctrine-extensions with Symfony
symfony/apache-pack                  v1.0.1    A pack for Apache support in Symfony
symfony/asset                        v5.4.19   Manages URL generation and versioning of web assets such as CSS stylesheets, JavaScript files and ima...
symfony/browser-kit                  v6.2.5    Simulates the behavior of a web browser, allowing you to make requests, click on links and submit for...
symfony/cache                        v6.2.5    Provides extended PSR-6, PSR-16 (and tags) implementations
symfony/cache-contracts              v3.2.0    Generic abstractions related to caching
symfony/config                       v6.2.5    Helps you find, load, combine, autofill and validate configuration values of any kind
symfony/console                      v6.2.5    Eases the creation of beautiful and testable command line interfaces
symfony/css-selector                 v6.2.5    Converts CSS selectors to XPath expressions
symfony/dependency-injection         v6.1.12   Allows you to standardize and centralize the way objects are constructed in your application
symfony/deprecation-contracts        v3.2.0    A generic function and convention to trigger deprecation notices
symfony/doctrine-bridge              v5.4.19   Provides integration for Doctrine with various Symfony components
symfony/doctrine-messenger           v6.2.5    Symfony Doctrine Messenger Bridge
symfony/dom-crawler                  v6.2.5    Eases DOM navigation for HTML and XML documents
symfony/dotenv                       v6.2.5    Registers environment variables from a .env file
symfony/error-handler                v6.2.5    Provides tools to manage errors and ease debugging PHP code
symfony/event-dispatcher             v6.2.5    Provides tools that allow your application components to communicate with each other by dispatching e...
symfony/event-dispatcher-contracts   v3.2.0    Generic abstractions related to dispatching event
symfony/expression-language          v5.4.19   Provides an engine that can compile and evaluate expressions
symfony/filesystem                   v6.2.5    Provides basic utilities for the filesystem
symfony/finder                       v6.2.5    Finds files and directories via an intuitive fluent interface
symfony/flex                         v2.2.5    Composer plugin for Symfony
symfony/framework-bundle             v6.0.19   Provides a tight integration between Symfony components and the Symfony full-stack framework
symfony/http-client                  v6.2.6    Provides powerful methods to fetch HTTP resources synchronously or asynchronously
symfony/http-client-contracts        v3.2.0    Generic abstractions related to HTTP clients
symfony/http-foundation              v6.2.6    Defines an object-oriented layer for the HTTP specification
symfony/http-kernel                  v6.1.12   Provides a structured process for converting a Request into a Response
symfony/mailer                       v6.1.11   Helps sending emails
symfony/maker-bundle                 v1.48.0   Symfony Maker helps you create empty commands, controllers, form classes, tests and more so you can f...
symfony/messenger                    v6.2.5    Helps applications send and receive messages to/from other applications or via message queues
symfony/mime                         v6.1.11   Allows manipulating MIME messages
symfony/monolog-bridge               v5.4.19   Provides integration for Monolog with various Symfony components
symfony/monolog-bundle               v3.8.0    Symfony MonologBundle
symfony/options-resolver             v6.2.5    Provides an improved replacement for the array_replace PHP function
symfony/password-hasher              v6.2.5    Provides password hashing utilities
symfony/phpunit-bridge               v6.2.5    Provides utilities for PHPUnit, especially user deprecation notices management
symfony/polyfill-intl-grapheme       v1.27.0   Symfony polyfill for intl's grapheme_* functions
symfony/polyfill-intl-idn            v1.27.0   Symfony polyfill for intl's idn_to_ascii and idn_to_utf8 functions
symfony/polyfill-intl-normalizer     v1.27.0   Symfony polyfill for intl's Normalizer class and related functions
symfony/polyfill-mbstring            v1.27.0   Symfony polyfill for the Mbstring extension
symfony/polyfill-php72               v1.27.0   Symfony polyfill backporting some PHP 7.2+ features to lower PHP versions
symfony/polyfill-php73               v1.27.0   Symfony polyfill backporting some PHP 7.3+ features to lower PHP versions
symfony/polyfill-php80               v1.27.0   Symfony polyfill backporting some PHP 8.0+ features to lower PHP versions
symfony/polyfill-php81               v1.27.0   Symfony polyfill backporting some PHP 8.1+ features to lower PHP versions
symfony/property-access              v5.4.19   Provides functions to read and write from/to an object or array using a simple string notation
symfony/property-info                v5.4.19   Extracts information about PHP class' properties using metadata of popular sources
symfony/proxy-manager-bridge         v5.4.19   Provides integration for ProxyManager with various Symfony components
symfony/routing                      v6.2.5    Maps an HTTP request to a set of configuration variables
symfony/security                     2.0.6     Symfony Security Component
symfony/security-bundle              v5.4.20   Provides a tight integration of the Security component into the Symfony full-stack framework
symfony/security-core                v5.4.19   Symfony Security Component - Core Library
symfony/security-csrf                v6.2.5    Symfony Security Component - CSRF Library
symfony/security-guard               v5.4.19   Symfony Security Component - Guard
symfony/security-http                v5.4.20   Symfony Security Component - HTTP Integration
symfony/serializer                   v5.4.19   Handles serializing and deserializing data structures, including object graphs, into array structures...
symfony/service-contracts            v2.5.2    Generic abstractions related to writing services
symfony/stopwatch                    v6.2.5    Provides a way to profile code
symfony/string                       v6.2.5    Provides an object-oriented API to strings and deals with bytes, UTF-8 code points and grapheme clust...
symfony/translation-contracts        v3.2.0    Generic abstractions related to translation
symfony/twig-bridge                  v6.1.11   Provides integration for Twig with various Symfony components
symfony/twig-bundle                  v5.4.19   Provides a tight integration of Twig into the Symfony full-stack framework
symfony/validator                    v5.4.19   Provides tools to validate values
symfony/var-dumper                   v6.2.5    Provides mechanisms for walking through any arbitrary PHP variable
symfony/var-exporter                 v6.2.5    Allows exporting any serializable PHP data structure to plain PHP code
symfony/web-link                     v6.2.5    Manages links between resources
symfony/webpack-encore-bundle        v1.16.1   Integration with your Symfony app & Webpack Encore!
symfony/yaml                         v6.2.5    Loads and dumps YAML files

已通过将doctrine/mongodb-odm从2.4.3版本降级至2.3.1版本解决问题，现需了解该错误的根本原因及更优解决方案。

• ODM内部实现bug：Doctrine MongoDB ODM 2.4.3版本中，DefaultPersistentCollectionFactory类在实例化PersistentCollection时未传递构造函数所需的3个参数，直接调用了空构造，导致参数不足异常。这是该版本的已知问题，后续小版本已修复。
• 依赖版本不兼容：项目中doctrine/collections版本为1.8.0，而ODM 2.4.x系列需要doctrine/collections≥2.0版本，低版本集合库与ODM核心的接口不匹配，间接导致集合实例化失败。
• API Platform触发场景：当API Platform处理请求并序列化实体关联集合时，会调用ODM的集合工厂创建实例，此时工厂的错误实现直接暴露了参数问题。

方案1：升级到修复后的ODM版本 #

直接升级doctrine/mongodb-odm到2.4.4及以上版本（该版本已修复集合工厂的参数传递问题），同时升级doctrine/collections到兼容的2.x版本：

composer require doctrine/mongodb-odm:^2.4.4 doctrine/collections:^2.0

同步升级doctrine/mongodb-odm-bundle到与ODM核心匹配的最新版本，避免bundle与核心库版本不兼容。

方案2：锁定稳定兼容版本组合 #

如果升级存在其他依赖冲突，可在composer.json中明确锁定经过验证的稳定版本：

{
  "require": {
    "doctrine/mongodb-odm": "2.3.1",
    "doctrine/mongodb-odm-bundle": "4.4.0"
  }
}

执行composer update doctrine/mongodb-odm doctrine/mongodb-odm-bundle完成依赖更新，确保版本组合稳定。

方案3：检查实体映射配置 #

部分情况下，实体中关联集合的映射注解错误（如@ReferenceMany缺少必要参数、关联类型定义错误）也可能触发此类异常。检查所有MongoDB实体的关联配置，确保符合ODM 2.x的规范。

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