README

为 Syde WordPress 项目设计的 PHP 7.4+ 编码规范。

用法

当通过 Composer 安装此软件包并更新依赖项时，一切就绪，可以通过以下方式检查编码规范：

vendor/bin/phpcs --standard="Inpsyde" <path>

在这里，<path> 至少是一个要检查的文件或目录，例如

vendor/bin/phpcs --standard="Inpsyde" ./src/ ./my-plugin.php

可以使用许多选项来自定义命令的行为，要获取文档，请使用

vendor/bin/phpcs --help

配置文件

可以使用 phpcs.xml.dist 文件来避免通过命令行传递许多参数。例如

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

    <description>My Project coding standard.</description>

    <file>./src</file>
    <file>./tests/src</file>

    <arg value="sp"/>
    <arg name="colors"/>

    <config name="testVersion" value="7.4-"/>
    <config name="text_domain" value="my-project"/>

    <rule ref="Inpsyde">
        <exclude name="WordPress.PHP.DiscouragedPHPFunctions.serialize_serialize"/>
    </rule>

    <rule ref="Inpsyde.CodeQuality.Psr4">
        <properties>
            <property
                name="psr4"
                type="array"
                value="
                    Inpsyde\MyProject=>src,
                    Inpsyde\MyProject\Tests=>tests/src|tests/unit
                "/>
        </properties>
    </rule>

</ruleset>

这样的配置可以像这样运行代码风格检查

vendor/bin/phpcs

此外，多亏了 text_domain 设置，PHP_CodeSniffer 还会检查所有 WordPress 国际化函数是否都使用正确的文本域。

包含的规则

有关包含规则的详细列表，请参阅 ruleset.xml。

PSR-1, PSR-2, PSR-12

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

• PSR-1
• PSR-2
• PSR-12

WordPress 编码规范

为确保代码质量，并与 WordPress VIP 兼容，已从以下规范中包含了一些规则：

• WordPress 编码规范
• VIP 编码规范

Slevomat

已从 Slevomat 编码规范 包含了一些规则。

PHPCompatibility

为了进行 PHP 交叉版本兼容性检查，已包含完整的 PHP 代码规范 PHP CodeSniffer 标准。

可以通过自定义 phpcs.xml 文件来更改目标 PHP 版本（范围）。

通用规则

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

自定义规则

正在使用以下自定义规则

有关 注释和配置，请参阅此存储库中的 inpsyde-custom-sniffs.md 文件。

模板规则

InpsydeTemplates 规则集通过添加一些特定于模板的嗅探器扩展了标准的 Inpsyde 规则集。

使用 InpsydeTemplates 规则集的推荐方法如下

<ruleset>
    <file>./src</file>
    <file>./templates</file>
    <file>./tests</file>
    <file>./views</file>

    <rule ref="Inpsyde"/>

    <rule ref="InpsydeTemplates">
        <include-pattern>*/templates/*</include-pattern>
        <include-pattern>*/views/*</include-pattern>
    </rule>
</ruleset>

以下模板特定的规则可用

删除或禁用规则

规则树

有时需要不遵循某些规则。为了避免错误报告，可以通过配置来

• 通过配置删除整个项目的规则；
• 仅从代码中的特定位置禁用规则。

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

• 一个完整标准；
• 标准子集；
• 单个嗅探器；
• 单个规则。

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

通过配置文件删除规则

可以通过自定义 phpcs.xml 文件删除整个项目的规则，如下所示

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

    <rule ref="Inpsyde">
        <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 Wiki。

IDE集成

PhpStorm

如上所述安装包后，打开PhpStorm设置，并导航到

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

在"配置"下拉菜单中选择"本地"。

单击下拉菜单旁边的"..."按钮。它将显示一个对话框，您需要在该对话框中指定PHP_CodeSniffer可执行文件的路徑。

打开文件选择对话框，导航到您的项目中的vendor/bin/，并选择phpcs。在Windows上，选择phpcs.bat。

单击路径输入字段旁边的"验证"按钮。如果一切正常，窗口底部将显示一条成功消息。

仍然在PhpStorm设置中，导航到

编辑器 -> 检查

在检查列表之前搜索框中输入codesniffer，然后选择

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

使用列表中的复选框启用它，按"应用"。

选择"PHP_CodeSniffer验证"，单击右侧"编码标准"下拉菜单旁边的刷新图标，并选择Inpsyde。

如果您在此处看不到Inpsyde，您可能需要通过选择"自定义"作为标准并使用下拉菜单旁边的"..."按钮来指定phpcs.xml文件。

一旦完成PhpStorm集成，您的代码中的警告和错误将自动显示在IDE编辑器中。

安装

通过Composer，将以下内容作为开发依赖项添加

composer require "inpsyde/php-coding-standards:^2@dev" --dev

（请注意，一旦发布了稳定的2.0.0版本，或如果您的根包最低稳定性为dev，则可以删除@dev）。