PHP-CS-Fixer `phpdoc_types` 规则完全指南：统一 PHPDoc 标准类型的大小写-北京尧图网络

PHP-CS-Fixerphpdoc_types规则完全指南统一 PHPDoc 标准类型的大小写【免费下载链接】PHP-CS-FixerA tool to automatically fix PHP Coding Standards issues项目地址: https://gitcode.com/gh_mirrors/ph/PHP-CS-Fixer导读本文围绕 PHP-CS-Fixer 中的phpdoc_types规则展开介绍它如何在 PHPDoc 注释中强制使用 PHP 标准类型的正确大小写如把STRING修正为string、inT修正为int并深入讲解exclude与groups两个可配置选项、典型配置示例、底层实现原理以及它在PhpCsFixer、Symfony规则集中的地位。读完本文你将掌握如何在项目中启用、定制和排查该规则并能理解其与 TypeExpression、AbstractPhpdocTypesFixer 等源码组件的协作机制。规则概述为什么 PHPDoc 中的类型大小写很重要phpdoc_types是 PHP-CS-Fixer 提供的 PHPDoc 类规则之一其唯一职责是PHPDoc 中的标准 PHP 类型必须使用正确的大小写。它并不改变类型语义也不替换别名类型那是phpdoc_scalar规则的工作只专注于让string、int、bool、array、mixed、void等标准类型的书写规范统一。源码中的定义位于 src/Fixer/Phpdoc/PhpdocTypesFixer.phppublic function getDefinition(): FixerDefinitionInterface { return new FixerDefinition( The correct case must be used for standard PHP types in PHPDoc., ... ); }它继承自AbstractPhpdocTypesFixer见 src/AbstractPhpdocTypesFixer.php该抽象基类负责在 Tokenizer 层面扫描所有T_DOC_COMMENT逐一解析注释中的注解并提取类型表达式最终交由子类实现的具体normalize()逻辑完成大小写归一。适用场景phpdoc_types最典型的使用场景包括团队协作项目不同开发者习惯书写STRING、Bool、integer、Mixed等不同大小写风格规则可一键统一与静态分析工具配合PHPStan、Psalm 等工具对 PHPDoc 类型解析更严格统一的大小写能减少误报编码规范落地作为Symfony、PhpCsFixer规则集的组成部分随规则集开箱即用。支持的注解标签范围该规则不只处理param和return。通过基类中的applyFix()实现src/AbstractPhpdocTypesFixer.php可以看到它处理所有属于Annotation::TAGS_WITH_TYPES的注解。该常量定义于 src/DocBlock/Annotation.php包括extends, implements, method, param, param-out, phpstan-import-type, phpstan-type, phpstan-var, property, property-read, property-write, psalm-import-type, psalm-type, psalm-var, return, throws, type, var也就是说var、property、method、throws、phpstan-type等注解中的类型同样会被检查和修正。配置选项phpdoc_types是CONFIGURABLE可配置规则支持exclude与groups两个选项。其配置解析逻辑在 src/Fixer/Phpdoc/PhpdocTypesFixer.php 的createConfigurationDefinition()中定义。exclude类型string[]字符串数组作用从待修复类型中排除指定类型无论其属于哪个分组允许值[$this, array, bool, boolean, callable, double, false, float, int, integer, iterable, mixed, null, object, parent, resource, scalar, self, static, string, true, void]的子集默认值[]不排除任何类型// 示例不修复 resource 类型 -setRules([ phpdoc_types [exclude [resource]], ])groups类型string[]字符串数组作用指定要修复的类型分组允许值[alias, meta, simple]的子集默认值[alias, meta, simple]全部分组类型分组定义于 src/Fixer/Phpdoc/PhpdocTypesFixer.php 的POSSIBLE_TYPES常量分组包含类型说明aliasboolean、double、integer传统别名规范大小写后保持原样不替换为bool等meta$this、false、mixed、parent、resource、scalar、self、static、true、void语义型/伪类型simplearray、bool、callable、float、int、iterable、null、object、stringPHP 原生简单类型// 示例只修复 simple 与 alias 分组 -setRules([ phpdoc_types [groups [simple, alias]], ])注意groups只决定哪些分组参与修复属于选定分组但大小写已经正确的类型不会被改动。配置示例与预期效果原文档doc/rules/phpdoc/phpdoc_types.rst给出了三个可复现的示例以下逐一说明。示例 1默认配置默认配置groups与exclude均使用默认值下param STRING|String[] $bar与return inT[]会被修正为/** - * param STRING|String[] $bar * param string|string[] $bar * - * return inT[] * return int[] */注意String[]中作为数组元素类型的String同样被修正说明规则会深入到复合类型内部。示例 2[groups [simple, alias]]当只启用simple与alias分组时/** - * param BOOL $foo * param bool $foo * * return MIXED */BOOL属于simple分组被修正为bool而MIXED属于meta分组因该分组未启用而保持原样。示例 3[exclude [resource]]当排除了resource类型时/** * param Resource $foo * - * return VOID * return void */Resource因被exclude排除而保持原样VOID属于meta分组仍被修正为void。测试用例 tests/Fixer/Phpdoc/PhpdocTypesFixerTest.php 也明确验证了exclude resource preserves Resource casing的行为。在实际配置文件中启用在项目的.php-cs-fixer.dist.php配置文件中可以按需组合使用。完整示例可参考 doc/config.rst?php $finder (new PhpCsFixer\Finder()) -in(__DIR__) ; return (new PhpCsFixer\Config()) -setRules([ // 方式一直接使用规则集推荐规则默认开启 Symfony true, // 方式二单独启用并定制 phpdoc_types [groups [simple, alias], exclude [resource]], ]) -setFinder($finder) ;提示若使用Symfony或PhpCsFixer规则集phpdoc_types已默认启用无需再单独声明只有需要覆盖默认行为时才显式配置。底层实现原理1. 候选判定基类 src/AbstractPhpdocTypesFixer.php 通过isCandidate()检查文件 Token 流中是否存在T_DOC_COMMENTpublic function isCandidate(Tokens $tokens): bool { return $tokens-isTokenKindFound(\T_DOC_COMMENT); }2. 注解解析与类型提取applyFix()遍历所有文档注释使用DocBlock与Annotation类解析出所有带类型的注解然后对每个注解调用fixType()最终通过TypeExpression的类型表达式树逐层处理。完整链路为Tokenizer Tokens → DocBlock → Annotation::getTypeExpression() → TypeExpression::mapTypes() → 子类 normalize() → 回写 Token其中TypeExpression::mapTypes()src/DocBlock/TypeExpression.php会递归遍历类型表达式中的每个子类型并对变更做精确的字符串替换保证不误伤其他字符。3. 大小写归一策略PhpdocTypesFixer::normalize()src/Fixer/Phpdoc/PhpdocTypesFixer.php是核心逻辑protected function normalize(string $type): string { $typeExpression new TypeExpression($type, null, []); $newTypeExpression $typeExpression-mapTypes(function (TypeExpression $type) { if ($type-isUnionType()) { return $type; } $value $type-toString(); $valueLower strtolower($value); if (isset($this-typesSetToFix[$valueLower])) { return new TypeExpression($valueLower, null, []); } return $type; }); return $newTypeExpression-toString(); }关键点先将类型字符串转小写再去查typesSetToFix哈希表由configurePostNormalisation()依据groups合并、再剔除exclude后构建见 src/Fixer/Phpdoc/PhpdocTypesFixer.php因此无论原大小写如何都能命中只对标准类型进行归一类名如Foo、Callback、命名空间类如DoNotChangeThisAsThisIsAClass不会被改动测试用例Callback class in phpdoc must not be lowered验证了这一点见 tests/Fixer/Phpdoc/PhpdocTypesFixerTest.php联合类型union外层不直接转换而是递归进入内部各成员分别处理例如SELF|Array|Foo中只修正SELF与Array。4. 优先级设计getPriority()返回16src/Fixer/Phpdoc/PhpdocTypesFixer.php并声明必须早于phpdoc_scalar、phpdoc_align、phpdoc_types_order、phpdoc_no_empty_return、phpdoc_to_param_type等大量 PHPDoc 相关规则运行必须晚于phpdoc_indent运行。原因在于类型大小写的改变可能影响参数对齐phpdoc_align与别名替换phpdoc_scalar等后续规则的输入而phpdoc_indent需要先完成缩进因此该规则被安排在 PHPDoc 修复管线中较早的位置执行。支持的语法形态基于测试用例官方测试 tests/Fixer/Phpdoc/PhpdocTypesFixerTest.php 覆盖了大量现代 PHPDoc 语法这些行为都属于向后兼容承诺的一部分语法形态示例行为可空类型return ?inT→return ?int修正?后的类型嵌套数组return INT[][][]→return int[][][]递归修正泛型param ARRAYINT, OBJECT→param arrayint, object修正泛型内部类型Foo\Int\Bar这类命名空间类名不动callable 签名param CALLABLE(BOOL, INT): FLOAT→param callable(bool, int): float修正参数与返回值类型数组形状shapereturn array{FOO: BOOL, ...}修正值类型键名FOO不视为类型字符串字面量类型NULL、NULL保持不动裸NULL修正为null区分字面量与类型名方法名与类型同名method bool BOOL(): void返回类型修正方法名BOOL不动行内文档param array $stuffs { var Bool $foo }递归修正嵌套注解多行数组泛型跨行的array INT, STRING 修正跨行类型窗口换行CRLF含\r\n的注释正常修正同时无效配置会被拒绝[groups [__TEST__]]与[exclude [__INVALID__]]都会抛出InvalidFixerConfigurationException见 tests/Fixer/Phpdoc/PhpdocTypesFixerTest.php错误信息形如[phpdoc_types] Invalid configuration: The option groups ...。规则集归属phpdoc_types是以下官方规则集的组成部分PhpCsFixer见 doc/ruleSets/PhpCsFixer.rstSymfony见 doc/ruleSets/Symfony.rst这意味着启用Symfony或PhpCsFixer的项目无需额外配置即可获得该规则的自动修复能力。与其他 PHPDoc 规则的关系在 PHP-CS-Fixer 的 PHPDoc 规则生态中phpdoc_types只负责大小写与其他规则分工明确phpdoc_scalar负责别名替换如boolean→bool、integer→int、double→float运行于phpdoc_types之后phpdoc_types_order负责联合类型排序如null置后phpdoc_align负责param等注解的对齐依赖已修正的类型宽度。正因如此phpdoc_types被设计为 PHPDoc 修复管线中最早执行的规则之一优先级 16确保后续规则基于规范化的类型输入工作。参考链接规则文档doc/rules/phpdoc/phpdoc_types.rstFixer 实现src/Fixer/Phpdoc/PhpdocTypesFixer.php抽象基类src/AbstractPhpdocTypesFixer.php类型表达式解析器src/DocBlock/TypeExpression.php注解标签常量src/DocBlock/Annotation.php官方测试tests/Fixer/Phpdoc/PhpdocTypesFixerTest.php配置文件指南doc/config.rst【免费下载链接】PHP-CS-FixerA tool to automatically fix PHP Coding Standards issues项目地址: https://gitcode.com/gh_mirrors/ph/PHP-CS-Fixer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

PHP-CS-Fixer `phpdoc_types` 规则完全指南：统一 PHPDoc 标准类型的大小写

相关推荐

戴卫国手写实现图解：3分钟搞定环境配置，底层原理全揭秘

COMSOL中光纤布拉格光栅(FBG)仿真建模全指南

HTN领域调试的3个坎儿：无限递归、循环检测、约束冲突

更多资讯

重新模糊增强：隐式扩散模型Python实现与避坑指南

PowerDC直流压降仿真实例：从1.5V电源网络设计到优化

用Sigrity PowerDC做直流压降仿真：从建模到瓶颈定位

电子工艺实操手册：从元件识读到焊点质量的量化标准

侧方位停车视频实战：3个最佳实践让面试原理不再卡壳

Triton Inference Server 分类扩展（Classification Extension）实战：HTTP/REST 与 gRPC 用法及源码原理

今日更新

2k显示屏性能优化踩坑：版本升级后API全变了，这份源码解析救了我

3步搞定美眉图实战项目，告别官方文档抓不住重点

3步搞定黄金大劫案项目搭建从入门到精通

本周精选

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？