PHP-CS-Fixer `trim_array_spaces` 规则详解：让数组书写像函数参数一样紧凑

PHP-CS-Fixertrim_array_spaces规则详解让数组书写像函数参数一样紧凑【免费下载链接】PHP-CS-FixerA tool to automatically fix PHP Coding Standards issues项目地址: https://gitcode.com/gh_mirrors/ph/PHP-CS-Fixer导读trim_array_spaces是 PHP CS Fixer 内置的一条数组符号Array Notation格式化规则用于去除数组开闭括号内侧多余的首尾空格使array( a, b )这类写法被统一为array(a, b)让数组字面量与函数/方法调用参数保持一致的视觉风格。本文以 trim_array_spaces.rst 官方文档为骨架深入 TrimArraySpacesFixer 源码与 官方测试集说明该规则的格式化行为、边界条件、所属规则集以及如何在本项目中实际启用它。规则要解决的问题在 PHP 代码中数组有两种书写形态长语法array(...)与短语法[...]。不同开发者在书写时可能习惯在括号内侧留一个空格例如$sample array( ); // 空数组括号内有多余空格 $sample array( a, b ); // 首尾各留一个空格这类写法虽然语法合法但在团队协作中会造成风格不统一也与“函数/方法参数不加首尾空格”的普遍约定相悖。trim_array_spaces规则的目标正是数组字面量应当像函数/方法参数一样格式化即开闭括号内侧不保留单行空格。官方文档给出的改造示例diff如下--- Original New ?php -$sample array( ); -$sample array( a, b ); $sample array(); $sample array(a, b);注意?php行前的空格仅用于 diff 展示实际代码中不存在。改造后空数组array()与带元素数组array(a, b)的开闭括号内侧均不再有空格。修复器源码如何判定与修剪该规则对应的修复器类是PhpCsFixer\Fixer\ArrayNotation\TrimArraySpacesFixer位于 src/Fixer/ArrayNotation/TrimArraySpacesFixer.php。它继承自AbstractFixersrc/AbstractFixer.php没有配置项、不属于 risky 规则因此可直接安全启用。候选判定isCandidatepublic function isCandidate(Tokens $tokens): bool { return $tokens-isAnyTokenKindsFound([\T_ARRAY, CT::T_ARRAY_BRACKET_OPEN, CT::T_DESTRUCTURING_BRACKET_OPEN]); }修复器只会在 Token 流中出现以下三类 token 时才进行修复Token含义\T_ARRAY长语法array(...)关键字CT::T_ARRAY_BRACKET_OPEN短语法[...]的开括号CT::T_DESTRUCTURING_BRACKET_OPEN数组解构赋值destructuring的[...]开括号其中CT::T_ARRAY_BRACKET_OPEN等是 PHP CS Fixer 自定义的常量 token定义见 src/Tokenizer/CT.php用于区分“数组字面量括号”与“索引访问括号”保证不会误伤$arr[ 0 ]这类下标访问写法下标空格由no_spaces_around_offset等规则负责。括号配对定位fixArrayif ($tokens[$startIndex]-isGivenKind(\T_ARRAY)) { $startIndex $tokens-getNextMeaningfulToken($startIndex); $endIndex $tokens-findBlockEnd(Tokens::BLOCK_TYPE_PARENTHESIS, $startIndex); } elseif ($tokens[$startIndex]-isGivenKind(CT::T_DESTRUCTURING_BRACKET_OPEN)) { $endIndex $tokens-findBlockEnd(Tokens::BLOCK_TYPE_DESTRUCTURING_BRACKET, $startIndex); } else { $endIndex $tokens-findBlockEnd(Tokens::BLOCK_TYPE_ARRAY_BRACKET, $startIndex); }逻辑要点长语法array(...)先跳过array关键字找到(再用findBlockEnd(BLOCK_TYPE_PARENTHESIS, ...)找到配对的)短语法[...]直接以[为起点找配对的]解构[...] $data按BLOCK_TYPE_DESTRUCTURING_BRACKET配对因此[url $url] $data;这类左侧解构也会被正确修剪测试用例array destructuring专门覆盖了此场景。首尾空格修剪策略修复器分别检查开括号后的第一个 token 与闭括号前的最后一个 token开头若开括号后紧跟的是纯空格/制表符isWhitespace( \t)且后续不是注释或满足注释场景的例外条件则清除该空格 token结尾若闭括号前是空格/制表符且前一个有意义 token 不是逗号则清除该空格 token。两个值得注意的细节只处理空格与制表符isWhitespace( \t)明确只匹配空格和 Tab不包含换行符因此多行数组的换行缩进不会被破坏。测试用例中array( \nbar\n );这类多行数组保持不变。保留尾逗号场景array( foo, bar, );中闭括号前的空白紧跟在逗号之后此时不修剪条件!$prevNonWhitespaceToken-equals(,)从而与whitespace_after_comma_in_array、尾逗号相关规则的行为协调避免规则间冲突。边界行为注释、字符串与多行数组从 TrimArraySpacesFixerTest 的测试数据可以确认以下边界行为这些行为共同构成该规则的向后兼容承诺backward compatibility promise块注释紧贴括号时不强制修剪array( /* empty array */ );在首部带注释且注释后紧跟闭括号时不会被改写源码中$nextNonWhitespaceIndex $prevNonWhitespaceIndex与str_starts_with($nextNonWhitespaceToken-getContent(), /*)等条件而array( /* empty array */ );中开括号后的空格在“注释是唯一内容”的场景下会被保留避免破坏注释排版。多行块注释场景如array(\n /* empty\n array */ )结尾多余空格则会被修剪掉结尾空格。多行数组不做单行化处理只要元素之间出现换行括号内侧换行及其缩进保持不变例如带//行注释的多行数组原样保留。注释与字符串中的“伪数组”不处理someFunc([/* array( foo, bar, [ foo ] ) */]);中注释文本里的array(...)、字符串字面量$bar array( foo );内的数组写法均不会被误修因为 token 化之后它们只是注释/字符串内容。嵌套数组逐层修剪array( array( foo ), array( bar ) );的内外层括号空格都会被递归处理applyFix遍历全部 token遇到数组开括号即调用fixArray测试中甚至覆盖了“垃圾堆”级别的多层嵌套数组嵌套闭包、闭包默认参数里再嵌套数组、注释里再写数组等组合场景。函数默认参数中的数组同样处理function(array $foo array( bar )) {}会被整理为function(array $foo array(bar)) {}。闭包、方法调用、三元表达式等复杂元素array( $bar-method(), Foo::doSomething() );、array( $y ? true : false );、array( function() {...} );等元素的数组首尾空格均被去除而元素内部的空格如方法参数内空格不受影响。yield返回数组yield array( a 1, b 2 );同样被修剪为yield array(a 1, b 2);。同语句多个数组一行内多个数组含长短语法混用、嵌套会全部被处理。所属规则集Symfony 与 PhpCsFixer官方文档明确该规则是以下两个内置规则集的组成部分Symfony遵循官方 Symfony 编码规范基于PER-CS扩展其中以默认配置启用trim_array_spaces无额外参数。PhpCsFixerPHP CS Fixer 团队高度主观推荐的规则集扩展自PER-CS与Symfony因此同样包含trim_array_spaces。也就是说只要你的项目启用了Symfony或PhpCsFixer规则集该规则就会自动生效无需单独配置。它也出现在规则总览 doc/rules/index.rst 的 Array Notation 分类下描述为“Arrays should be formatted like function/method arguments, without leading or trailing single line space.”非 risky、非 configurable。在本项目中启用与验证安装与运行按 README.md 推荐方式安装PHP 7.4 ~ 8.5 环境composer require --dev friendsofphp/php-cs-fixer # 或依赖冲突时使用 shim 包 composer require --dev php-cs-fixer/shim在仓库根目录可直接运行参考 doc/usage.rst 的fix命令用法# 使用项目配置文件.php-cs-fixer.php 等修复 php php-cs-fixer fix # 仅检查而不修改文件 php php-cs-fixer check # 指定路径、开启差异输出 php php-cs-fixer fix src/Fixer/ArrayNotation --diff # 查看实际修改的 diff php php-cs-fixer fix . --dry-run --diff单独启用或排除该规则如果不想使用整个规则集可通过--rules显式选择php php-cs-fixer fix . --rulestrim_array_spaces也可以从规则集中排除规则名前加-php php-cs-fixer fix . --rulesSymfony,-trim_array_spaces在.php-cs-fixer.php配置文件中同样可以精确控制?php return (new PhpCsFixer\Config()) -setRules([ Symfony true, trim_array_spaces true, // 显式声明等价于默认启用 ]) ;用测试验证行为该规则的行为由官方测试 tests/Fixer/ArrayNotation/TrimArraySpacesFixerTest.php 固化测试类基于AbstractFixerTestCase通过数据提供器逐一断言输入/输出对。运行方式php vendor/bin/phpunit tests/Fixer/ArrayNotation/TrimArraySpacesFixerTest.php每一条测试用例都属于项目的向后兼容承诺即官方保证该规则的既有行为在后续版本中不会随意改变。若你为自定义规则编写测试可参照同样的模式。与相邻数组规则的分工PHP CS Fixer 的 Array Notation 分类下还有多条与空格相关的规则理解它们的分工有助于避免重复配置规则职责trim_array_spaces本文去除数组开闭括号内侧的首尾空格whitespace_after_comma_in_array保证数组逗号之后有一个空格no_whitespace_before_comma_in_array禁止数组逗号之前出现空格no_whitespace_in_empty_array空数组[]内不得只含空白与trim_array_spaces在空数组场景有重叠后者同样会清除array( )中的空格array_syntax统一使用长语法array()或短语法[]no_multiline_whitespace_around_double_arrow处理两侧的多行空白从 Symfony 规则集可以看到这些规则往往成套出现、各司其职共同保证数组书写风格的一致性。小结trim_array_spaces是一条无配置、非 risky的数组格式规则核心行为是去除数组括号内侧的单行首尾空格使数组书写与函数参数一致。修复器通过 token 级定位T_ARRAY/CT::T_ARRAY_BRACKET_OPEN/CT::T_DESTRUCTURING_BRACKET_OPEN精准识别数组字面量仅清除空格与制表符不影响多行数组的换行缩进。注释、字符串内的伪数组写法不会被误伤尾逗号场景刻意保留避免与其他规则冲突。该规则默认包含在Symfony与PhpCsFixer两个主流规则集中也可通过--rulestrim_array_spaces单独启用。全部行为均有官方测试用例背书属于项目向后兼容承诺的一部分可放心用于团队代码风格统一。【免费下载链接】PHP-CS-FixerA tool to automatically fix PHP Coding Standards issues项目地址: https://gitcode.com/gh_mirrors/ph/PHP-CS-Fixer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考