如何使用 PHPCS 强制属性命名采用 snake_case 风格

在PHP项目中，类属性命名风格的统一是代码可读性和团队协作的基础。但直接用PHPCS原生规则来强制属性使用snake_case，往往会踩到不少坑。本文将介绍一种精准、高效的解决方案，避免误伤局部变量或函数参数。

咱们在实际项目中，经常会遇到一个头疼的问题：怎么用PHP_CodeSniffer（PHPCS）强制要求类属性（properties）必须使用`$snake_case`，而不是驼峰（camelCase）或帕斯卡（PascalCase）？这看似简单，但如果不了解它的“脾气”，很容易把规则配置得一团糟。

先说说PHPCS本身。它自带的规则集，比如Squiz、PSR12，主要关注变量名是不是驼峰风格。但关键问题是，它并没有一个专门针对“类属性”强制使用蛇形命名的独立规则。你可能会想到用``这条规则，但它的范围太宽了，会检查所有变量，包括局部变量、函数参数，而且它的逻辑是“只要不是驼峰就报错”，而不是“必须是蛇形”。这显然不是我们想要的。

那么，正确的做法是什么？答案就是引入WordPress Coding Standards（WPCS）。它里面藏着一个专门为属性量身定做的规则：

这条规则的精妙之处在于，它只检查类属性，比如`public $foo_bar;`或`private $user_id;`。如果遇到`$firstName`或`$FirstName`这种非蛇形写法，它会直接报错。而像`foreach ($items as $item_name)`中的`$item_name`这样的局部变量，或者函数参数，它完全不会管。这就实现了作用域的精准控制，避免了误伤。

当然，使用这条规则需要做好一些准备工作：

• 首先，确保你已经安装了WPCS：composer require --dev wp-coding-standards/wpcs
• 然后，执行命令让PHPCS知道WPCS的位置：phpcbf --config-set installed_paths vendor/wp-coding-standards/wpcs
• 最后，在你的`phpcs.xml`或`ruleset.xml`配置文件中，引用上面那条规则。

这里有几个重要提醒：

• 千万不要混用`Squiz.NamingConventions.ValidVariableName`这类粗粒度的规则，否则很容易导致重复报错或误判。
• `VariableNotSnakeCase`规则默认只检查属性，但为了更明确，你也可以通过``来显式强化一下，不过这通常不是必须的。
• 如果你的项目已经使用了PSR-12标准，建议将这条WPCS规则放在自定义的ruleset中，并合理排序，以避免潜在的规则冲突。
• 最后，运行修复命令`phpcbf --standard=YourRuleset .`，PHPCS会自动帮你把违规的属性名重命名为蛇形格式，比如`$userID`会自动变成`$user_id`。

总结一下：PHPCS原生能力有限，而WPCS提供了语义清晰、范围精准的`WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase`规则，这是目前强制类属性使用`$snake_case`的最佳实践方案，没有之一。