README

提供 Brianvarskonst 编码标准的 PHP CodeSniffer 规则集

概述

Brianvarskonst 编码标准是 Symfony 编码标准的扩展，并增加了确保代码质量和一致性的特定规则。

PHP 8.0+ 编码标准

规则

Brianvarskonst.Array.ArrayDoubleArrowAlignment

=> 操作符必须在关联数组中对齐。
键和 => 操作符必须在数组中位于同一行。

Brianvarskonst.Array.MultiLineArray

在多行数组中，开括号后必须跟一个换行符。
闭括号必须独占一行。
多行数组中的元素必须缩进。

Brianvarskonst.Formatting.AlphabeticalUseStatements

use 语句必须按字典顺序排序。
通过 order 属性配置排序顺序。

配置

Brianvarskonst.Formatting.AlphabeticalUseStatements 的 order 属性定义了用于排序的函数。

排序的可能值

dictionary（默认）：基于 strcmp，命名空间分隔符位于任何其他字符之前
```
use Doctrine\ORM\Query;
use Doctrine\ORM\Query\Expr;
use Doctrine\ORM\QueryBuilder;
```

string：使用 strcmp 的二进制安全的字符串比较

use Doctrine\ORM\Query;
use Doctrine\ORM\QueryBuilder;
use Doctrine\ORM\Query\Expr;

use ExampleSub;
use Examples;

string-locale：使用 strcoll 的基于区域的字符串比较
string-case-insensitive：使用 strcasecmp 的二进制安全的不区分大小写的字符串比较
```
use Examples;
use ExampleSub;
```

要更改项目中排序顺序，请将以下片段添加到自定义 ruleset.xml

<rule ref="Brianvarskonst.Formatting.AlphabeticalUseStatements">
    <properties>
        <property name="order" value="string-locale"/>
    </properties>
</rule>

Brianvarskonst.Formatting.UnnecessaryNamespaceUsageSniff

当使用 use 语句导入时，必须使用导入的类名。

Brianvarskonst.String.VariableInDoubleQuotes

双引号字符串中的插值变量必须用 {} 包围，例如 {$VAR} 而不是 $VAR。

Brianvarskonst.WhiteSpace.ConstantSpacing

const 后必须跟一个空格。

Brianvarskonst.WhiteSpace.MultipleEmptyLines

来源： mediawiki/mediawiki-codesniffer

不允许存在多于一个连续的空行。

Brianvarskonst.Usage.ElementNameMinimalLength

函数、类、接口、特质和常量必须使用最小长度的名称（默认 3 个字符）。
通过 minLength 和 allowedShortNames 配置。

<rule ref="Brianvarskonst.Usage.ElementNameMinimalLength">
    <properties>
        <property name="minLength" value="5"/>
        <property name="allowedShortNames" type="array" value="id,db,ok,x,y"/>
    </properties>
</rule>

也可以通过 additionalAllowedNames 配置扩展白名单，例如。

<rule ref="Brianvarskonst.Usage.ElementNameMinimalLength">
    <properties>
        <property name="additionalAllowedNames" type="array" value="i,j" />
    </properties>
</rule>

Brianvarskonst.Complexity.NestingLevel

确保函数/方法内的最大嵌套级别。
默认情况下，在级别 3 时触发警告，在级别 5 时触发错误。
通过 warningLimit 和 errorLimit 配置。

例如

function foo(bool $level_one, array $level_two, bool $level_three)
{
    if ($level_one) {
        foreach ($level_two as $value) {
            if ($level_three) {
                return $value;
            }
        }
    }

    return '';
}

示例代码包含一个 3 级嵌套级别。

默认情况下，如果嵌套等于或大于 3，则触发警告，如果嵌套等于或大于 5，则触发错误。

可以通过分别通过 warningLimit 和 errorLimit 属性来定制警告和错误限制。

<rule ref="Brianvarskonst.Complexity.NestingLevel">
    <properties>
        <property name="warningLimit" value="5" />
        <property name="errorLimit" value="10" />
    </properties>
</rule>

存在一个例外。通常，try/catch/finally 块会计算嵌套级别，但此嗅探器忽略了由函数内部的 try/catch/finally 造成的级别增加。

例如，以下代码是可行的

function bar(array $data, string $foo): string
{
    // Indent level 1
    try {
        $encoded = json_encode($data, JSON_THROW_ON_ERROR);
        // Indent level 2
        if ($encoded) {
            // Indent level 3
            if ($append !== '') {
                return $encoded . $foo;
            }

            return $encoded;
        }

        return '';
    } catch (\Throwable $e) {
        return '';
    }
}

事实上，嵌套的两个if将占据2个缩进级别，加上3个级别的try/catch块，但由于try/catch直接位于函数内部，所以会被忽略，因此sniff所考虑的最大级别是2，这在限制范围内。

关于try/catch/finally块的这个异常可以通过ignoreTopLevelTryBlock属性禁用

<rule ref="Brianvarskonst.Complexity.NestingLevel">
    <properties>
        <property name="errorLimit" value="10" />
        <property name="ignoreTopLevelTryBlock" value="false" />
    </properties>
</rule>

Brianvarskonst.Classes.PropertyPerClassLimit

确保每个类（默认10个）的最大属性数。
可以通过maxCount进行配置。

<rule ref="Brianvarskonst.Classes.PropertyPerClassLimit">
    <properties>
        <property name="maxCount" value="120" />
    </properties>
</rule>

Brianvarskonst.Namespace.Psr4

强制执行PSR-4自动加载标准。
可配置以匹配composer.json自动加载设置。

我们的风格强制使用PSR-4进行自动加载。此sniff使用一些配置来检查包含类的文件是否使用PSR-4期望的结构保存。如果没有提供配置，sniff只检查类名和文件名匹配，但这并不是PSR-4的保证。

所需的配置与composer.json中PSR-4配置相同

{
  "autoload": {
    "psr-4": {
      "Brianvarskonst\\Foo\\": "src/"
    }
  },
  "autoload-dev": {
    "psr-4": {
      "Brianvarskonst\\Foo\\Tests\\": "tests/php/"
    }
  }
}

规则配置应为

<rule ref="Brianvarskonst.Namespace.Psr4">
    <properties>
        <property name="psr4" type="array" value="Brianvarskonst\Foo=>src,Brianvarskonst\Foo\Tests=>tests/php" />
    </properties>
</rule>

请注意，当提供PSR-4配置时，所有可自动加载的实体（类/接口/特质）都将被检查是否符合规范。如果sniffer目标路径中有不符合PSR-4规范的实体（例如，通过classmap加载或根本不自动加载），则应通过exclude属性排除，例如

<rule ref="Brianvarskonst.Namespace.Psr4">
    <properties>
        <property name="psr4" type="array" value="Brianvarskonst\SomeCode=>src" />
        <property name="exclude" type="array" value="Brianvarskonst\ExcludeThis,Brianvarskonst\AndThis" />
    </properties>
</rule>

请注意，任何以exclude数组中任何值开头的项目都将被排除。

例如，通过排除Brianvarskonst\ExcludeThis，将排除类似Brianvarskonst\ExcludeThis\Foo和Brianvarskonst\ExcludeThis\Bar\Baz的项目。

要确保要排除的是命名空间，而不是具有相同名称的类，只需使用\作为最后一个字符。

包含的规则

其他标准中还有更多规则被导入，具体请参阅ruleset.xml。

大多数问题都可以使用phpcbf自动修复。

PSR-1，PSR-2，PSR-12

有关从PHP标准建议（PSR）包含的规则的信息，请参阅官方文档

Slevomat

一些规则已从Slevomat编码标准中包含。

Symfony

一些规则已从Symfony编码标准中包含。

通用规则

一些规则也来自PHP_CodeSniffer本身，以及PHPCSExtra。

要求

PHP
Composer

安装

Composer

使用Composer是首选方法。

将Brianvarskonst编码标准添加到composer.json

$ composer require --dev brianvarskonst/coding-standard

使用编码标准

$ ./vendor/bin/phpcs --standard=Brianvarskonst path/to/my/file.php

可选地，将Brianvarskonst设置为默认编码标准

$ ./vendor/bin/phpcs --config-set default_standard Brianvarskonst

源代码

克隆存储库

$ git clone https://github.com/brianvarskonst/coding-standard.git

安装依赖项

$ composer install

验证编码标准

$ ./vendor/bin/phpcs -i

使用编码标准

$ ./vendor/bin/phpcs --standard=Brianvarskonst path/to/my/file.php

可选地，将Brianvarskonst设置为默认编码标准

$ ./vendor/bin/phpcs --config-set default_standard Brianvarskonst

故障排除

如果phpcs抱怨Brianvarskonst编码标准未安装，请使用phpcs -i检查已安装的编码标准，并使用phpcs --config-show检查installed_paths是否设置正确

删除或禁用规则

规则树

有时不遵循某些规则是必要的。为了避免错误报告，你可以

通过配置删除整个项目的规则。
在代码的特定位置禁用规则。

在这两种情况下，都可以删除或禁用

一个完整的标准
标准子集
单个sniff
单个规则

这些元素之间存在层次关系：标准由一个或多个子集组成，这些子集包含一个或多个嗅探器，而嗅探器又包含一个或多个规则。

通过配置文件删除规则

可以使用自定义的phpcs.xml文件删除整个项目中的规则，例如

<?xml version="1.0"?>
<ruleset name="MyProjectCodingStandard">

    <rule ref="Brianvarskonst">
        <exclude name="PSR1.Classes.ClassDeclaration"/>
    </rule>

</ruleset>

在上面的示例中，已删除了PSR1.Classes.ClassDeclaration嗅探器（及其包含的所有规则）。

使用PSR1而不是PSR1.Classes.ClassDeclaration将删除整个PSR1标准。而使用PSR1.Classes.ClassDeclaration.MultipleClasses只会删除这个规则，而不会影响PSR1.Classes.ClassDeclaration嗅探器中的其他规则。

通过代码注释删除规则

仅针对特定文件或其部分删除规则/嗅探器/子集/标准，可以使用特殊的phpcs注释。例如，使用// phpcs:disable后跟可选的标准/子集/嗅探器/规则名称。如下所示

// phpcs:disable PSR1.Classes.ClassDeclaration

有关忽略文件的信息，请参阅官方PHP_CodeSniffer 维基。

IDE 集成

PhpStorm

按照上述说明安装编码标准包后，按照以下步骤配置PhpStorm以使用PHP_CodeSniffer

打开PhpStorm设置，并导航到

语言与框架 -> PHP -> 质量工具 -> PHP_CodeSniffer。

在配置下拉菜单中，选择本地。
单击下拉菜单旁边的...按钮，打开用于指定PHP_CodeSniffer可执行文件路径的对话框。
在文件选择对话框中，导航到项目目录中的vendor/bin/，并选择phpcs。在Windows上，选择phpcs.bat。
单击路径输入字段旁边的验证按钮。如果一切设置正确，窗口底部将出现一条成功消息。
仍然在PhpStorm设置中，导航到

编辑器 -> 检查

在搜索框中输入codesniffer，然后选择

PHP -> 质量工具 -> PHP_CodeSniffer 验证

通过勾选相应的复选框并单击应用来启用它。
选择PHP_CodeSniffer 验证，然后单击右侧编码标准下拉菜单旁边的刷新图标，并选择Brianvarskonst。
- 如果Brianvarskonst未列出，请选择自定义作为标准，并使用下拉菜单旁边的...按钮指定phpcs.xml文件。

一旦PhpStorm与PHP_CodeSniffer集成，警告和错误将在您的IDE编辑器中自动突出显示。

依赖关系

贡献

有关信息，请参阅CONTRIBUTING.md。

brianvarskonst / coding-standard

维护者

详细信息