升级Mautic至PHP 8.x：寻求基于正确类型重写PHPDocs的工具

实用工具推荐 #

• PHPStan：主打类型检测，能精准揪出PHPDocs类型不符、滥用mixed的问题。搭配phpstan/phpstan-deprecation-rules和phpstan/phpstan-phpunit扩展，跑phpstan analyse就能拿到详细的问题报告，方便批量定位需要修正的点。
• Psalm：自带自动修复能力，用psalm --fix能自动修正不少简单的PHPDocs类型错误，比如把明显不符合实际的mixed替换为推断出的具体类型。还支持psalm --alter命令批量调整PHPDocs，适合处理大量重复场景。
• Rector自定义规则：既然Rector因为坏的PHPDocs卡壳，可以写轻量自定义规则先清理PHPDocs。比如通过Rector的节点分析，推断属性、方法的实际类型，自动替换错误的@var、@param、@return标注——比如检测到方法固定返回Contact实例，就把@return mixed改成@return Contact。
• PHP-CS-Fixer：用自带的phpdoc_*规则（比如phpdoc_types_order、phpdoc_no_empty_return）规范PHPDocs格式，同时修正一些低级类型错误，比如把混乱的类型顺序理清楚，或者移除无意义的mixed标注。

手动辅助技巧 #

• 优先处理核心类：先修Mautic核心模块（Model、Controller层）的PHPDocs，这些类依赖最多，修复后能让Rector先推进大部分代码的升级。
• IDE批量修正：用PhpStorm的「Inspect Code」功能检测类型不匹配，再用「Apply Fix」批量修复单个类或目录的问题，适合小范围精准调整。
• 上下文推断类型：碰到mixed类型时，看属性赋值、方法调用的上下文——比如属性只被赋值为DateTime实例，直接把@var mixed改成@var DateTime就行。

适配Rector的临时方案 #

• 先跳过PHPDocs规则：在Rector配置里暂时关闭和PHPDocs相关的规则，先处理代码结构升级（比如PHP8语法替换、废弃函数移除），之后再统一收拾PHPDocs。
• 先用Rector内置规则清理：启用Rector的PhpDocTypesFixerRule相关规则，先把明显错误的PHPDocs修正，再跑核心升级流程。

内容的提问来源于stack exchange，提问作者Mohammad Abu Musa