启用Xdebug覆盖率后与nikic/php-parser 4.x兼容问题求助

本地环境信息：

• PHP 8.1.20 + Xdebug 3.3.1
• PHPUnit 9.5.28
• Symfony框架，Docker容器部署
• nikic/php-parser 4.x（项目依赖包）

启用Xdebug的coverage模式后，执行PHPUnit测试触发致命错误：

[14-Mar-2024 16:28:52 UTC] PHP Fatal error:  Declaration of PhpParser\ParserAbstract::parse(string $code, ?PhpParser\ErrorHandler $errorHandler = null) must be compatible with PhpParser\Parser::parse(string $code, ?PhpParser\ErrorHandler $errorHandler = null): ?array in vendor/nikic/php-parser/lib/PhpParser/ParserAbstract.php on line 158

关闭coverage模式后测试可正常执行，更新php-parser及依赖包无效果。

• 限制Xdebug覆盖率扫描范围
  Xdebug默认会对所有PHP文件（包括vendor目录）插桩，这可能触发php-parser的兼容性问题。启用白名单模式，仅对项目源码目录进行覆盖率收集：
  运行PHPUnit时添加参数：

  php -dxdebug.mode=coverage -dxdebug.coverage_enable=whitelist -dxdebug.coverage_whitelist=/path/to/your/project/src vendor/bin/phpunit
  

  也可在php.ini中配置：

  xdebug.mode = coverage
  xdebug.coverage_enable = whitelist
  xdebug.coverage_whitelist = /path/to/your/project/src
  

• 锁定php-parser到4.x最新稳定版
  执行命令更新到4.x分支的最新版本，确保方法声明匹配：

  composer require nikic/php-parser:^4.17 --update-with-dependencies
  

  同时检查composer.lock，确认无其他依赖强制拉取旧版本的php-parser。

• 临时禁用OPcache
  OPcache的缓存可能导致类声明不一致，运行测试时临时关闭：

  php -dxdebug.mode=coverage -dopcache.enable=0 vendor/bin/phpunit
  

• 降级Xdebug版本
  尝试将Xdebug从3.3.x降级到3.2.x（如3.2.2），部分版本的插桩逻辑可能避免该冲突，在Dockerfile中修改Xdebug的安装版本即可。

• 排查项目类重定义
  检查项目代码、配置文件中是否存在对PhpParser类的重定义、别名或自定义扩展，这类操作可能在Xdebug插桩后引发兼容性问题。

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