Composer在线学习地址：学习地址
在现代 php 开发中，代码规范和质量是团队协作和项目长期维护的关键。我们常常依赖像 php-cs-fixer 这样的工具来自动化代码格式化，确保风格统一。然而，有一个细节常常被忽视，却又至关重要：docblock 注释中类名的引用方式。
想象一下，你在阅读一段代码，其中一个方法的参数类型或者返回值类型在 DocBlock 中被声明为
User。这个
User到底是
App\Models\User还是
App\Services\User？如果没有明确的命名空间，或者没有对应的
use语句，IDE 可能会“懵圈”，无法提供准确的自动补全，静态分析工具也可能报错或给出错误的警告。更糟糕的是，当项目重构，类文件移动或命名空间改变时，这些不规范的 DocBlock 引用很容易变成“幽灵引用”，导致潜在的运行时问题。
手动去检查和修正每一个 DocBlock 显然是不现实的，尤其是在大型项目中。我们渴望一种自动化、强制性的解决方案。幸好，PHP 生态的强大之处就在于其丰富的社区贡献，
adamwojs/php-cs-fixer-phpdoc-force-fqcn就是为了解决这个痛点而生。
解决方案：adamwojs/php-cs-fixer-phpdoc-force-fqcn
这个 Composer 包提供了一个 PHP-CS-Fixer 规则，它的唯一目的就是：强制你在 DocBlock 注释中使用完全限定类名（FQCN）。这意味着，无论你的类在哪里被引用，它都会被修正为
\Namespace\SubNamespace\ClassName的形式，从而彻底消除歧义。
如何安装
作为一个开发工具，我们通过 Composer 将它作为开发依赖安装：
立即学习“PHP免费学习笔记（深入）”；
composer require --dev adamwojs/php-cs-fixer-phpdoc-force-fqcn
如何使用
安装完成后，你需要在项目的
.php_cs.dist或
.php_cs配置文件中注册并启用这个新的规则。如果你正在使用 PHP-CS-Fixer 2.x 版本，配置方式如下：
<?php
// .php_cs.dist 或 .php_cs 文件
return PhpCsFixer\Config::create()
// (1) 注册 \AdamWojs\PhpCsFixerPhpdocForceFQCN\Fixer\Phpdoc\ForceFQCNFixer 修复器
->registerCustomFixers([
new \AdamWojs\PhpCsFixerPhpdocForceFQCN\Fixer\Phpdoc\ForceFQCNFixer()
])
->setRules([
// ... 其他你已有的规则
// (2) 启用 AdamWojs/phpdoc_force_fqcn_fixer 规则
'AdamWojs/phpdoc_force_fqcn_fixer' => true,
])
// ... 其他配置，如 setFinder()
;完成配置后，当你运行
php-cs-fixer fix命令时，它就会自动扫描你的代码，并修正 DocBlock 中的类名引用，确保它们都是 FQCN。
带来的巨大优势
引入
adamwojs/php-cs-fixer-phpdoc-force-fqcn规则，看似只是一个小小的改动，却能为你的项目带来多方面实实在在的提升：
- 代码可读性与一致性大幅提升： 所有 DocBlock 中的类名都将是明确无误的 FQCN，团队成员无需猜测或查找，一眼就能知道引用的具体是哪个类。
- IDE 智能提示与自动补全更精准： IDE 能准确识别 DocBlock 中的类型，提供更智能、更准确的自动补全建议，显著提升开发效率。
- 静态分析工具的得力助手： PHPStan、Psalm 等静态分析工具能够基于 FQCN 进行更准确的类型检查和潜在问题发现，减少运行时错误。
- 降低重构风险： 当你移动或重命名类时，由于 DocBlock 中使用的是 FQCN，它们通常不会因为命名空间的变化而失效，减少了手动修正的工作量和出错的可能性。
- 强制团队编码规范： 将此规则集成到 CI/CD 流程中，可以强制团队成员遵守这一规范，从源头上保证代码质量。
- 减少代码审查的负担： 代码审查者可以把精力更多地放在业务逻辑和架构设计上，而不是纠结于 DocBlock 的格式问题。
结语
在 PHP 项目中，每一个微小的规范化努力都能积累成巨大的质量提升。
adamwojs/php-cs-fixer-phpdoc-force-fqcn便是这样一个简单却极具价值的工具。通过 Composer 的便捷安装和 PHP-CS-Fixer 的自动化能力，它能彻底解决 DocBlock 类名引用不规范的痛点，为你的代码库带来更高的可读性、更强的健壮性，以及更流畅的开发体验。如果你还没有在项目中使用它，强烈建议你尝试一下，你会发现它的价值远超你的想象！
