PHP-CS-Fixer 规则详解：no_whitespace_before_comma_in_array 清理数组逗号前的空白

• 开发工具
• 代码质量
• 静态分析
• Lint
• 格式化

本篇指南围绕 PHP-CS-Fixer 中数组符号（ArrayNotation）分组下的no_whitespace_before_comma_in_array规则展开，讲解其功能定位、after_heredoc配置项、底层 Tokenizer 实现原理，以及它在@Symfony与各 PHP 迁移规则集中的启用方式。读完你既能直接在.php-cs-fixer.php配置文件中使用该规则，也能从源码与测试层面理解它为何"安全地"改写数组而不会误伤函数调用、注释或匿名类。

规则概述：它到底修什么

该规则的核心语义只有一句话：在数组声明中，每个逗号之前不得存在空白字符。例如下面这种"逗号前留空格"的写法会被自动修正：

--- Original +++ New -<?php $x = array(1 , "2"); +<?php $x = array(1, "2");

对应的规则描述定义在 NoWhitespaceBeforeCommaInArrayFixer.php 的getDefinition()中：'In array declaration, there MUST NOT be a whitespace before each comma.'，即遵循 PSR 风格中"逗号前无空格、逗号后跟一个空格"的通用排版约定。它既处理旧式array(...)语法，也处理 PHP 5.4+ 的短数组[...]语法。

一个容易混淆的点：本规则不负责处理逗号之后的空白（那是whitespace_after_comma_in_array规则的职责），也不负责删除逗号本身，它只精确地删除"位于数组逗号之前"的空白。

工作原理：从源码看它如何安全地改写

该规则不是用正则表达式粗暴替换，而是基于 PHP-CS-Fixer 的 Tokenizer 体系工作。它在 src/Fixer/ArrayNotation/NoWhitespaceBeforeCommaInArrayFixer.php 中实现，类结构上继承AbstractFixer并实现ConfigurableFixerInterface（通过ConfigurableFixerTrait获得configure()能力）。

处理流程分三步，可以从源码逐段印证：

1. 候选判定isCandidate()（源码）：只有当代码中出现了T_ARRAY（即array关键字）或CT::T_ARRAY_BRACKET_OPEN（即[短数组括号，是 PHP-CS-Fixer 自定义的常量类型，定义在 src/Tokenizer/CT.php）时，该文件才进入修复流程。没有数组的纯函数调用文件会被快速跳过。

2. 反向遍历applyFix()（源码）：从 token 流的末尾向开头遍历，遇到array或[就调用fixSpacing()。反向遍历保证了嵌套数组（array(array(...))）从内向外处理时索引不会错乱。

3. 精准删除fixSpacing()与skipNonArrayElements()（源码）：先通过findBlockEnd()找到数组块的结束位置，再反向扫描；对每个逗号 token，用getPrevNonWhitespace()找到其前一个有效 token，然后调用Tokens::removeLeadingWhitespace()（定义在 src/Tokenizer/Tokens.php）删除逗号前的空白。

skipNonArrayElements()是这个规则的"防误伤"核心：它负责跳过数组内部嵌套的{...}代码块和(...)函数调用括号，确保只处理数组自己的逗号。例如[1, foo(1 , 2), 3]中的foo(1 , 2)内部逗号不会被本规则改动。

配置项：after_heredoc

该规则是**可配置（CONFIGURABLE）**的，唯一的配置项是after_heredoc。在 createConfigurationDefinition() 中可以看到它的完整定义：

默认配置下，规则对 heredoc 结束标记（T_END_HEREDOC）与逗号之间的空白采取"保守"态度：不删除。判断逻辑见 fixSpacing()：当after_heredoc为false时，如果逗号前一个 token 是T_END_HEREDOC，则跳过不处理。

future-mode 与默认值迁移

文档中标注的"Default value (future-mode):true"对应源码中的Future::getV4OrV3(true, false)（见 源码）。这是 PHP-CS-Fixer 的版本迁移机制：在当前版本下返回false（v3 行为），而在未来主版本（v4）中默认值将变为true。开发者可以通过设置环境变量PHP_CS_FIXER_FUTURE_MODE=1提前体验未来版本的默认行为（判定逻辑见 src/Future.php），但生产环境建议显式配置选项，避免未来升级时格式化结果发生意外变化。

配置示例

在项目根目录的.php-cs-fixer.php配置文件中，可以这样显式启用：

<?php $finder = PhpCsFixer\Finder::create() ->in(__DIR__.'/src'); return (new PhpCsFixer\Config()) ->setRules([ // 默认行为：不触碰 heredoc 结束标记后的空白 'no_whitespace_before_comma_in_array' => true, // 或者显式开启对 heredoc 的处理 // 'no_whitespace_before_comma_in_array' => ['after_heredoc' => true], ]) ->setFinder($finder);

配置解析由ConfigurableFixerTrait::configure()调用FixerConfigurationResolver完成（见 src/Fixer/ConfigurableFixerTrait.php），如果传入非bool值，会抛出InvalidFixerConfigurationException。

行为示例：两种配置的差异

示例一：默认配置

使用默认配置（after_heredoc => false），普通数组逗号前的空白被删除：

--- Original +++ New -<?php $x = array(1 , "2"); +<?php $x = array(1, "2");

示例二：['after_heredoc' => true]

当启用after_heredoc后，heredoc 结束标记EOD与逗号之间的空白也会被移除：

--- Original +++ New <?php $x = [<<<EOD foo -EOD - , 'bar' +EOD, 'bar' ];

边界行为：哪些情况它绝不改动

该规则的测试类 NoWhitespaceBeforeCommaInArrayFixerTest.php 被官方文档声明为"向后兼容承诺的一部分"，其中覆盖了大量边界场景，值得逐一了解：

• 注释前的逗号：若逗号前紧邻的是注释 token，则不删除空白（源码!$tokens[$prevIndex]->isComment()判断），避免破坏注释与代码的排版（测试用例见 测试文件）。
• 函数调用内部的逗号：getValue(1,2 ,3)中的逗号不属于数组声明，不会被改动（测试用例）。
• 匿名函数与匿名类：function( $x ,$y) {...}参数列表、匿名类的implements Foo , Bar列表都不受影响（测试用例），但数组内部嵌套的短数组[$x , $y]仍会被修复。
• 关联数组与嵌套数组：["a" => $a , "b" => "b"]、[5 ,6, 7]等多层结构都会被正确处理（测试用例）。
• 多行数组：跨行书写的数组，无论逗号是否位于行尾，逗号前的空白都会清理（测试用例）。
• 展开运算符：[...$foo , ...$bar]中的逗号同样会被修复（测试用例）。
• heredoc 元素：只有显式配置after_heredoc => true时，heredoc 结束标记与逗号之间的空白才被删除（测试用例）。

这些用例说明：该规则虽然名字简单，但实现上对 token 上下文做了细致区分，可以放心在包含复杂表达式的代码库中启用。

所属规则集：随迁移集与 Symfony 风格集一起启用

该规则是以下规则集的组成部分（均以['after_heredoc' => true]配置启用）：

• PHP 迁移规则集：@PHP7x3Migration、@PHP7x4Migration、@PHP8x0Migration、@PHP8x1Migration、@PHP8x2Migration、@PHP8x3Migration、@PHP8x4Migration、@PHP8x5Migration，以及已废弃的同名旧式名称@PHP73Migration、@PHP74Migration、@PHP80Migration、@PHP81Migration、@PHP82Migration、@PHP83Migration、@PHP84Migration、@PHP85Migration。
• 通用风格规则集：@PhpCsFixer、@Symfony。

从源码可以确认这种"链式继承"的机制：规则首先定义在 src/RuleSet/Sets/PHP7x3MigrationSet.php 中（与method_argument_space、trailing_comma_in_multiline一样都带after_heredoc => true），而后续迁移集通过'@PHP7x3Migration' => true引用基础集，例如 src/RuleSet/Sets/PHP7x4MigrationSet.php，因此该规则随迁移链一路向下传递；在 src/RuleSet/Sets/SymfonySet.php 中也能看到它被显式收录。

也就是说：如果你的项目直接使用@Symfony或任意@PHPxxMigration规则集，该规则默认就会生效，且采用的是开启 heredoc 处理的配置——这与单独启用规则时的默认值（false）并不相同，这是规则集设计上的有意选择，实践中值得留意。

如何验证与运行

可以先用describe命令查看该规则的官方说明与配置定义：

php php-cs-fixer describe no_whitespace_before_comma_in_array

随后对目标代码执行修复：

php php-cs-fixer fix path/to/file.php --rules='no_whitespace_before_comma_in_array' --dry-run --diff

其中--dry-run --diff组合只展示将被修改的 diff 而不真正写入文件，适合在接入 CI 前预览改动。若希望在整个项目启用该规则，推荐在.php-cs-fixer.php配置文件中通过setRules()显式声明（参考上文配置示例），或直接依赖@Symfony/ 迁移规则集。

小结

no_whitespace_before_comma_in_array是 PHP-CS-Fixer 中一条"小而精"的数组排版规则：默认清理数组声明中逗号前的空白，通过after_heredoc选项决定是否处理 heredoc 结束标记后的空白（当前默认false，未来版本将改为true）。它基于 Tokenizer 实现，能够精确区分数组逗号与函数调用、注释、匿名类等其他上下文中的逗号；同时它也是@Symfony与全部 PHP 迁移规则集的组成部分，随迁移链自动生效。理解它的默认值演变与边界行为，有助于你在配置规则集时做出明确的显式决策，避免未来升级带来的格式化差异。

• 开发工具
• 代码质量
• 静态分析
• Lint
• 格式化