PHP-CS-Fixer 的 native_type_declaration_casing 规则：原生类型声明大小写规范化实战指南

开发工具代码质量静态分析Lint格式化【免费下载链接】PHP-CS-FixerA tool to automatically fix PHP Coding Standards issues项目地址https://gitcode.com/gh_mirrors/ph/PHP-CS-Fixer点击查看免费下载本文围绕 PHP-CS-Fixer 中的native_type_declaration_casing规则展开深入讲解它如何将INT、CALLABLE、BOOL等大小写不规范的原生类型声明统一为小写形式覆盖可修复的场景、被刻意排除的边界情况、底层 Token 处理原理以及如何在Symfony/PhpCsFixer规则集中启用它。读完本文你将能够在实际项目中安全地启用该规则并理解它为什么不会误伤类名、常量名与命名空间片段。规则概述什么是 native_type_declaration_casingnative_type_declaration_casing是 PHP-CS-Fixer 中位于 Casing大小写分类下的一个内置规则官方定义为原生类型声明Native type declarations应使用正确的大小写Native type declarations should be used in the correct case.。PHP 是大小写不敏感的语言因此下面两种写法在运行时完全等价function Foo(INT $bar): VOID {} // 可以运行但风格混乱 function foo(int $bar): void {} // 符合主流编码规范该规则的作用就是扫描代码中的类型声明位置把所有大写的原生类型关键字统一改写成小写从而让代码风格保持一致。它对应源码为 NativeTypeDeclarationCasingFixer.php测试覆盖见 NativeTypeDeclarationCasingFixerTest.php。需要特别强调的是这里只处理原生内置类型例如int、string、array等。你自定义的类名、接口名、命名空间别名等不在处理范围内——它们通常需要遵循PascalCase等其他约定不应被强行小写。官方文档示例两种典型场景规则文档native_type_declaration_casing.rst给出了两个 diff 形式的示例直观展示了修复前后变化。示例一函数参数与返回类型--- Original New ?php class Bar { - public function Foo(CALLABLE $bar): INT public function Foo(callable $bar): int { return 1; } }这里同时处理了参数类型CALLABLE和返回类型INT分别改为callable与int。示例二类常量类型声明PHP 8.3--- Original New ?php class Foo { - const INT BAR 1; const int BAR 1; }PHP 8.3 起支持为类常量声明类型该规则同样会将其中的原生类型关键字规范化。支持修复的类型清单按 PHP 版本演进从源码 NativeTypeDeclarationCasingFixer.php 可以看到规则内部维护了一个$types集合只有命中该集合的类型才会被改写。集合内容与 PHP 版本强相关完整清单如下类型关键字引入版本说明selfPHP 5.0指向当前类arrayPHP 5.1数组callablePHP 5.4可调用类型bool/float/int/stringPHP 7.0标量类型iterable/voidPHP 7.1可迭代 / 无返回值objectPHP 7.2对象类型staticPHP 8.0仅作返回类型mixedPHP 8.0混合类型false/nullPHP 8.0联合返回类型中可用neverPHP 8.1仅作返回类型truePHP 8.2独立类型true-type RFCfalse/nullPHP 8.2独立类型RFC代码中的判定逻辑是$this-types [ array true, bool true, callable true, float true, int true, iterable true, object true, parent true, self true, static true, string true, void true, ]; if (\PHP_VERSION_ID 8_00_00) { /* false, mixed, null */ } if (\PHP_VERSION_ID 8_01_00) { $this-types[never] true; } if (\PHP_VERSION_ID 8_02_00) { $this-types[true] true; }可以看到false、null等关键字在低版本 PHP 中不是类型而是普通标识符因此规则会根据当前运行环境PHP_VERSION_ID动态决定是否把它们视为类型。例如在 PHP 8.0 以下环境中MIXED会被当作普通类名而保持不变——测试类中的testFixPre80用例NativeTypeDeclarationCasingFixerTest.php专门验证了这一点PHP 8.0 时private MIXED $m;不会被改写。实际修复效果与边界场景结合测试类 NativeTypeDeclarationCasingFixerTest.php 中的大量用例可以归纳出规则的实际行为边界。先看它会修复的场景// 函数参数与返回类型 function Foo(BOOL $a, FLOAT $b, INT $c, STRING $d): INT {} // 修复为function Foo(bool $a, float $b, int $c, string $d): int {} // 可空类型 ?type function Foo(?INT $A): VOID {} // 修复为function Foo(?int $A): void {} // 类属性类型 class Foo { private BOOL $c false; } // 修复为class Foo { private bool $c false; } // 联合类型PHP 8.0 function foo(INT|BOOL $x): INT|BOOL {} // 修复为function foo(int|bool $x): int|bool {} // 交叉类型、析取范式DNF类型 private (AB)|INT|D $d5; // INT 被修复为 int(AB) 中的类名不受影响 // 构造器属性提升promoted properties public function __construct(public INT $i, ...) {} // 修复为public function __construct(public int $i, ...) {} // 闭包与箭头函数 return fn (CALLABLE $c): INT 1; // 修复为return fn (callable $c): int 1; // readonly 属性PHP 8.1 private readonly ARRAY $ax; // 修复为 private readonly array $ax; // 类常量类型声明PHP 8.3 const INT SOME_INT 3; // 修复为 const int SOME_INT 3;再看它不会修复的场景这些正是避免误伤的关键类名与命名空间片段INTEGER、Foo\INT\B、String\A等不会被改写因为INTEGER不是原生类型关键字且A\INT\B中的INT是命名空间段常量名称const INT A;中INT是常量名而非类型保持不变属性名private $INT 1;中INT是属性名保持不变动态属性访问$this-Object-doBar();中Object是属性名保持不变switch case 与比较表达式case True:、True $x等中True/False是常量字面量不属于类型声明保持不变全局常量类外的const INT A;不会被修改。底层实现原理如何精准定位类型声明位置从源码结构看规则通过三层防线避免误伤这也是理解该规则稳健性的关键。第一步isCandidate 快速筛选isCandidate()源码在遍历 Token 前先做一次快速判断只有在以下情况才进入正式修复流程存在T_FUNCTION或T_FN普通函数、方法、闭包、箭头函数或存在类/接口/trait/enum 关键字Token::getClassyTokenKinds()且同时存在T_STRING或 PHP 8.3 时存在T_CONST且上下文中有类声明对应类常量类型声明场景。这个设计保证了绝大多数无关文件会被直接跳过提升整体处理性能。第二步类型白名单校验applyFix()源码遍历所有 Token对每个 Token 执行strtolower后检查是否命中$this-types白名单。大小写已经正确的 Token 直接跳过$content $lowercaseContent时continue。第三步前后 Token 语境判定这是最关键的一步。即使命中了白名单还要检查该 Token 的前一个有意义 Tokenprev和后一个有意义 Tokennext如果前一个是、T_CASE、T_OBJECT_OPERATOR-、T_DOUBLE_COLON::、T_NS_SEPARATOR\则跳过——这说明当前 Token 很可能是常量名、属性名或命名空间段如果后一个是或T_NS_SEPARATOR同样跳过——const INT 1或Foo\INT这类场景被排除只有前一个是T_CONST、CT::T_NULLABLE_TYPE?、CT::T_TYPE_ALTERNATION|、CT::T_TYPE_COLON:返回类型分隔符或者后一个是T_VARIABLE$a、CT::T_TYPE_ALTERNATION|时才确认当前 Token 确实处于类型声明位置执行小写替换。这套语境判定正是规则不误伤的核心保障。测试类中大量do not fix用例如public const ?INT\A XC;中INT保持不动、const ?BAR B null;中BAR保持不动验证了这些边界条件测试用例。如何启用该规则native_type_declaration_casing没有配置选项非可配置规则启用方式只有开启或关闭两种。方式一通过规则集启用根据文档与规则集源码该规则属于以下两个内置规则集Symfony在 SymfonySet.php 中以native_type_declaration_casing true显式启用对应规则集文档 Symfony.rstPhpCsFixerPhpCsFixerSet组合了Symfony等规则集因此同样包含该规则。在.php-cs-fixer.php配置文件中直接使用规则集即可?php return (new PhpCsFixer\Config()) -setRules([ Symfony true, ]) ;方式二单独启用如果不想引入整个规则集可以只开启这一条规则?php return (new PhpCsFixer\Config()) -setRules([ native_type_declaration_casing true, ]) ;运行命令# 检查模式下查看哪些文件会被修改 php php-cs-fixer fix --dry-run --diff --rulesnative_type_declaration_casing . # 直接应用修复 php php-cs-fixer fix --rulesnative_type_declaration_casing .注意事项与兼容性提示运行环境决定能力边界规则会根据当前 PHP 版本动态启用false、null、mixed、never、true等类型的修复。例如在 PHP 8.0 环境运行neverPHP 8.1与truePHP 8.2不会被识别为类型关键字相关代码会保持原样类常量类型声明的修复const INT FOO 6;仅在 PHP 8.3 时生效对应VersionSpecification(8_03_00)版本限定示例见 源码。与native_function_casing的区别native_function_casing处理的是函数调用如STRLEN改为strlen而本规则只处理类型声明两者作用域不同。类常量类型场景的兼容性PHP 8.3 之前类常量不支持类型声明因此示例二中的代码在旧版本上是语法错误——该规则只是将写法规范化为小写并不会改变 PHP 版本的兼容性边界。向后兼容承诺官方在规则文档末尾明确指出测试类NativeTypeDeclarationCasingFixerTest.php中定义的每个测试用例都是官方支持的正式行为属于向后兼容承诺的一部分。如果你的代码依赖规则对某个边界场景的处理可以参考该测试类确认预期行为。小结native_type_declaration_casing是一个简单但覆盖面很广的规范化规则它将参数类型、返回类型、属性类型、联合/交叉类型、可空类型以及 PHP 8.3 类常量类型中的原生类型关键字统一为小写同时通过精确的 Token 语境判定确保类名、常量名、属性名和命名空间段完全不受影响。配合Symfony或PhpCsFixer规则集使用可以低成本地消除代码库中类型声明大小写混用的风格问题。赞分享开发工具代码质量静态分析Lint格式化【免费下载链接】PHP-CS-FixerA tool to automatically fix PHP Coding Standards issues项目地址https://gitcode.com/gh_mirrors/ph/PHP-CS-Fixer点击查看免费下载相关推荐PHP-CS-Fixer native_function_type_declaration_casing 规则详解函数原生类型声明大小写规范化与迁移指南PHP CS Fixer native_function_type_declaration_casing 规则详解函数原生类型声明大小写规范化与迁移指南 本篇开发工具代码质量静态分析Lint格式化PHP-CS-Fixer blank_line_after_namespace 规则详解namespace 声明后的空行规范化PHP CS Fixer blank_line_after_namespace 规则详解namespace 声明后的空行规范化 导读 blank_line_a开发工具代码质量静态分析Lint格式化PHP-CS-Fixer 的 phpdoc_to_param_type 规则将 param 注解迁移为原生参数类型声明PHP CS Fixer 的 phpdoc_to_param_type 规则将 param 注解迁移为原生参数类型声明 导读 phpdoc_to_param开发工具代码质量静态分析Lint格式化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考