README

本软件包包含默认规则集和自定义规则，这些规则用于所有 best it 项目。

安装

可以使用以下命令使用 composer 安装我们的 PHP_CodeSniffer 包

composer require best-it/php_codesniffer --dev

请使用版本 1 以兼容 PHP 7.0！

使用方法

创建一个 PHP_CodeSniffer 配置文件（phpcs.xml.dist 或 phpcs.xml），如下所示

<?xml version="1.0"?>
<ruleset name="PROJECT-X">
    <description>The coding standard for project x.</description>

    <!-- Path to best it ruleset. -->
    <rule ref="./vendor/best-it/php_codesniffer/src/Standards/BestIt/ruleset.xml" />

    <!-- Path to directory which are checked. -->
    <file>src/</file>
    <file>tests/</file>
</ruleset>

如果您只想针对特殊的 PHP 版本进行嗅探，请声明一个 "testVersion"，如下所示

<config name="testVersion" value="7.1" />

然后包含

<rule ref="PHPCompatibility" />

在包含我们的规则集之后。（不要忘记 dev-require phpcompatibility/php-compatibility:^9.0。）

执行 PHP_CodeSniffer（路径可能会因您的 composer 配置而有所不同）

./vendor/bin/phpcs

我们使用警告来表示人类应该检查的内容，但这些内容不能使自动构建失败。如果您想看到警告但获得成功的构建，请使用具有特殊配置选项 ignore_warnings_on_exit

./vendor/bin/phpcs --config-set ignore_warnings_on_exit 1

或，如果您只想在单次运行中使用此选项

./vendor/bin/phpcs --runtime-set ignore_warnings_on_exit 1

查看原始文档以获取更多信息。

如果您想完全忽略警告，可以提供 cli 参数 n

./vendor/bin/phpcs -n

我们建议您不要忽略警告，而只是手动在拉取/合并请求中检查它们。

在 PHPStorm 中使用

如何在我们的最爱 IDE 中使用它？

文件/设置

... 然后选择我们的规则集。

使用的嗅探

BestIt 标准的基础是 PSR-12。

开发

简介

代码嗅探器基于基于标记的嗅探机制。

您可以使用代码嗅探器 CLI 的详细选项来查看在您的文件中哪些标记被解析在哪个位置。请参阅官方代码嗅探器教程以了解如何编写自定义嗅探的理论。

本教程的要点是，您需要实现 PHP_CodeSniffer\Sniffs\Sniff 接口，该接口强制执行两个方法

1. 标记注册

应返回您要嗅探的标记的解析器标记 ID 的 register 方法。

2. 处理

当调用 process 方法时，它带有您注册的标记在给定文件对象的标记堆栈中的位置。

best it "辅助工具"

BestIt\Sniffs\AbstractSniff

我们将基本工作重构到这个抽象中。您可以使用扩展 API 来获得更干净的 API，并跳过简单的模板。

areRequirementsMet：如果此方法返回 false，则嗅探器将被“跳过”。
isSniffSuppressed：如果此方法返回 true，则提供了抑制注释，并且嗅探器应该被“跳过”。
processToken：正常 API 的模板被保存在对象属性中，您可以在不“重新实现”带有其方法参数的基本接口的情况下嗅探您的标记。
setUp：您可以在使用 areRequirementsMet 检查需求之前设置测试。
tearDown：如果您想“销毁”此嗅探，您可以在嗅探处理之后将其拆除。

CodeSniffer 的目的是无状态的，即使嗅探类用作“单例”。因此，如果您在嗅探中保存状态，您必须之后进行 tearDown 或在 setUp 中正确初始化。

BestIt\Sniffs\DocTags\AbstractTagSniff

此抽象类帮助您嗅探单个文档标签。只需实现给定的抽象方法，您就可以注册和嗅探特定文档标签，并检查其内容直到换行符。

BestIt\Sniffs\DocTags\TagContentFormatTrait

此特性是为了补充 AbstractTagSniff，并提供一个 API，该 API 会自动将标签内容与正则表达式模式进行比较，如果不符合，则会导致带有 TagContentFormatInvalid 代码的错误或警告。

BestIt\Sniffs*RegistrationTrait

我们提供了一些特性，这些特性使得注册类似类的结构、常量、方法和属性的嗅探更加容易。

测试

要求

要能够测试我们编写的嗅探，请确保 composer 已经通过 --prefer-source 选项安装。这是必需的，因为我们使用了 SlevomatCodingStandard 的 TestCase。

错误代码作为公共常量

除了可读的/干净的代码之外，我们的测试基础还要求您提供错误代码作为公共常量，在嗅探类中以前缀 CODE_ 标识。

没有“Test”命名空间

我们的测试基础期望您在“正常”命名空间（BestIt）中提供一切。

帮助测试特性

令牌注册

特性 BestIt\Sniffs\TestTokenRegistrationTrait 帮助您测试已注册的令牌。

公共错误代码

特性 BestIt\Sniffs\TestRequiredConstantsTrait 帮助您测试错误代码。我们建议您测试这些值，因为它们可能是来自您的“客户”的“外部规则集”的一部分，您无法控制。因此，我们强制这些常量值保持 API 稳定！

默认集成测试

特性 BestIt\Sniffs\DefaultSniffIntegrationTestTrait 为您提供了三个测试，以测试基于嗅探个别测试文件的通常用例。

testCorrect
testErrors
testWarnings

要求

您的测试文件应该与您的嗅探（包括命名空间）完全相同，但后缀为 Test
提供一个名为 Fixtures 的文件夹作为您的测试文件的兄弟文件夹。
在您的“Fixtures”目录中创建一个与嗅探的简称相同的文件夹。

testCorrect

在您的 fixtures 目录中创建一个名为 correct 的文件夹。此文件夹中的每个 PHP 文件都将通过您的嗅探进行检查。嗅探可能不会为成功的测试生成错误和警告！

testErrors

在您的 fixtures 目录中创建一个名为 with_errors 的文件夹。此文件夹中的每个 PHP 文件都应该在您的嗅探中触发一个错误。您必须通过文件名提供错误结构。文件名必须匹配以下 pregex

/(?P<code>[\w]+)(\(\w*\))?\.(?P<errorLines>[\d-\,]+)(?P<fixedSuffix>\.fixed)?\.php/

文件名提供了关于应在哪些行发生哪些错误的信息。示例文件可以是 ErrorCode.1.php、ErrorCode.1,2,3.php、ErrorCode.1,2,3.fixed.php、ErrorCode(2).1,2,3.php、ErrorCode(2).1,2,3.fixed.php_。错误代码必须是您的嗅探中的原始代码值，第一个点之后的所有数字是错误的行。

如果您提供了一个以“fixed”结尾的附加文件，那么这是其错误兄弟的正确格式化的文件。

testWarnings

在您的 fixtures 目录中创建一个名为 with_warnings 的文件夹。此文件夹中的每个 PHP 文件都应该在您的嗅探中触发一个警告。您必须通过文件名提供警告结构。文件名必须匹配以下 pregex

/(?P<code>[\w]+)(\(\w*\))?\.(?P<errorLines>[\d-\,]+)(?P<fixedSuffix>\.fixed)?\.php/

文件名提供了关于哪一行应该出现哪个警告的信息。示例文件可以是 WarningCode.1.php, WarningCode.1,2,3.php, WarningCode.1,2,3.fixed.php，WarningCode(2).1,2,3.php, WarningCode(2).1,2,3.fixed.php_。警告代码必须是您嗅探器中的原始代码值，第一个点后面的数字是带有警告的行。