共享 PHPCS 规则在项目和团队之间

PHPCS 是一个开源的 CLI 工具，用于检测定义的编码标准的代码风格违规，并提供可自动修复规则的自动修复。我想说服你，即使你直接使用 Pint 或 PHP-CS-Fixer，你仍然应该考虑将 PHPCS 添加到你的工具库中。

在团队环境中跨多个项目定义 PHPCS 规则很繁琐，并且规则漂移在项目之间很可能会发生。您可能希望在您的项目中强制执行一致的规则，而无需过多思考或努力。

在本教程结束时，您将了解如何创建组织规则集，您可以使用它快速地对所有 PHP 项目进行 lint 检查。

在本系列的第 1 部分中，您学习了如何 在 Laravel 项目中使用 PHP Codesniffer。本教程将把我们在 Laravel 项目中创建的规则集移到专门的 Composer 包中。

#背景

您可能会问，“当我们有 Laravel Pint 和 PHP CS Fixer 时，为什么要使用 PHPCS？”与其将这些工具视为竞争对手，不如将它们视为互补工具，它们各自提供独特的、有价值的代码风格建议和修复。PHPCS 是一个 **代码风格检查器**，而 PHP-CS-Fixer 是一个 **代码修复器**。

确实，这些类型的工具有重叠之处：PHP-CS-Fixer 使用 `--dry-run` 功能具有代码风格检查功能。PHPCS 有一个 `phpcbf` CLI 工具可以自动修复 PHPCS 代码风格检查违规。但是，`phpcbf` 不会修复所有可用的规则。

例如，您可以配置 PHPCS 来检测和报告行长度违规；但是，PHPCS 无法自动修复这些违规，因为该工具无法确定您希望如何拆分长行。

屏幕截图说明了行长度配置，该配置在行超过 120 个字符时发出警告，并在行超过 80 个字符但仍在 120 个字符的最大阈值内时发出警告。这对于保持代码健康和检查诸如行长度之类的内容很有用。

#入门

我们需要创建一个新的 PHP Composer 包来创建自定义规则集，您可以在所有项目中重复使用它。PHPCS 需要了解这些规则集，因此我们将使用 Composer 安装程序 包，它可以轻松地通过 Composer 安装编码标准。

在开始之前，让我们创建一个包并初始化 Git 和 Composer

mkdir phpcs
cd phpcs
git init
composer init

运行 `composer init` 后，Composer 会提示您定义一些内容，例如您的包名。至少填写包名，可选地填写描述，并完成提示。我们将手动添加依赖项，所以不用担心以交互方式安装它们。

为了便于从 Composer 包中检测 PHPCS 标准，我们现在需要安装 Composer 安装程序包

composer require --dev \
  dealerdirect/phpcodesniffer-composer-installer

Composer 安装程序还要求您使用 `phpcodesniffer-standard` 定义 `type` 属性。Composer 安装程序插件使用所有项目已安装的 Composer 包中的 `type` 属性来搜索规则集。

最后，您的 `composer.json` 文件应该类似于以下内容

{
    "name": "bitpressio/phpcs",
    "type": "phpcodesniffer-standard",
    "authors": [
        {
            "name": "Paul Redmond",
            "email": "[email protected]"
        }
    ],
    "require-dev": {
        "dealerdirect/phpcodesniffer-composer-installer": "^1.0"
    },
    "config": {
        "allow-plugins": {
            "dealerdirect/phpcodesniffer-composer-installer": true
        }
    }
}

我们拥有定义 Composer 包所需的一切，我们只需要做的事情就是定义我们的规则集。

#定义规则集

我们的 Composer 包将包含我们的 `ruleset.xml` 文件，我们将在所有项目中安装它。我将我的规则集命名为 `Bitpress`，因此我需要在我的项目中创建一个文件夹来存放规则集

mkdir Bitpress
touch Bitpress/ruleset.xml

我们在 本系列的第 1 部分 中创建了一个规则集，因此将以下内容添加到 `ruleset.xml` 中，将值替换为您对规则集的命名

<?xml version="1.0"?>
<!-- @see https://pear.php.net/manual/en/package.php.php-codesniffer.annotated-ruleset.php -->
<ruleset name="Bitpress PHPCS Rules">
 
    <description>PHPCS ruleset for Bitpress</description>
 
    <!-- Use colors in output -->
    <arg name="colors"/>
 
    <!-- Show progress of the run -->
    <arg value="p"/>
 
    <!-- Show sniff codes in all reports -->
    <arg value="s"/>
 
    <!-- Our base rule: set to PSR12 -->
    <rule ref="PSR12">
        <exclude name="PSR12.Traits.UseDeclaration.MultipleImport" />
        <exclude name="PSR12.Operators.OperatorSpacing.NoSpaceBefore" />
        <exclude name="PSR12.Operators.OperatorSpacing.NoSpaceAfter" />
    </rule>
 
    <rule ref="Generic.Files.LineLength">
        <properties>
            <property name="lineLimit" value="80"/>
            <property name="absoluteLineLimit" value="120"/>
        </properties>
    </rule>
 
    <rule ref="PSR1.Methods.CamelCapsMethodName.NotCamelCaps">
        <exclude-pattern>tests/</exclude-pattern>
    </rule>
 
    <exclude-pattern>*/.phpstorm.meta.php</exclude-pattern>
    <exclude-pattern>*/_ide_helper.php</exclude-pattern>
    <exclude-pattern>*/*.blade.php</exclude-pattern>
    <exclude-pattern>*/autoload.php</exclude-pattern>
    <exclude-pattern>*/vendor/*</exclude-pattern>
 
</ruleset>

我们的规则集不会包含任何自定义代码风格检查，但我们将基于内置的 `PSR12` 规则集定义我们的首选设置。

我们拥有开始使用自定义规则集所需的一切！发布 Composer 包后，您可以将其作为 `--dev` 依赖项进行要求。

#在项目中设置规则集

发布 Composer 包后，您可以像这样在项目中安装它

composer require --dev bitpressio/phpcs

Composer 安装程序 依赖项将要求您授权执行代码，以便它可以检测和安装在 Composer 包中找到的标准。选择 `y` 以启用插件

此时，我们已经安装了自定义规则集，可以使用以下命令进行验证

vendor/bin/phpcs -i
The installed coding standards are
MySource, PEAR, PSR1, PSR2, PSR12, Squiz, Zend,
Bitpress and VariableAnalysis

`--show-info` 标志可以显示更多信息

vendor/bin/phpcs --config-show
Using config file: /Users/paul/code/sandbox/bitpress-phpcs/vendor/squizlabs/php_codesniffer/CodeSniffer.conf
 
installed_paths: ../../bitpressio/phpcs,../../sirbrillig/phpcs-variable-analysis

最后，我们可以使用以下命令将我们的规则集设为默认值

vendor/bin/phpcs --config-set default_standard Bitpress

我们可以让每个开发人员手动将我们的规则集设置为默认值；但是，使用 `composer.json`，我们可以使用以下方法自动触发它

"scripts": {
    "post-package-install": "vendor/bin/phpcs --config-set default_standard Bitpress"
}

如果我们重新运行我们的命令，我们的规则集现在应该是默认值

vendor/bin/phpcs --config-show
...
default_standard: Bitpress

我们快完成了，但我们还需要做一些小的调整才能完成安装。

#定义项目规则集配置

我们已经安装了规则集并将其设置为默认标准。但是，如果我们运行 `phpcs`，我们会收到以下消息

vendor/bin/phpcs
ERROR: You must supply at least one file or directory to process.
 
Run "phpcs --help" for usage information

虽然我们的规则集是默认值，但我们仍然需要提供配置来指示 PHPCS 应该对哪些文件和文件夹进行 lint 检查。让我们在项目的根目录中创建一个 `phpcs.xml` 文件

<?xml version="1.0"?>
<!-- @see https://pear.php.net/manual/en/package.php.php-codesniffer.annotated-ruleset.php -->
<ruleset name="My App">
    <file>app</file>
    <file>tests</file>
 
    <rule ref="Bitpress"></rule>
</ruleset>

如果您在项目中运行 `phpcs`（我在一个新的 Laravel 应用程序中测试了这一点），PHPCS 将对 `app/` 和 `tests/` 中的文件进行 lint 检查，并应该输出一些关于行长度的警告。随意根据自己的喜好配置这些路径。

#总结

在我们关于 PHPCS 规则集的快速浏览中，我们发布了一个包含自定义规则集的 Composer 包，我们可以将其共享到整个组织中。如果您希望在多个项目中进行一致的代码风格检查，希望这种方法可能会有所帮助。