README

🚧

这是一个工具集，用于协助开发者的 PHP CodeSniffer 检查。

安装
特性
贡献
许可

安装

Composer 项目基础安装

在项目的根目录下运行以下命令

composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer require --dev phpcsstandards/phpcsdevtools:^1.0

Composer 全局安装

如果您在几个不同的检查仓库中工作，您可能希望全局安装此工具集

composer global config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer global require --dev phpcsstandards/phpcsdevtools:^1.0

Composer 将自动安装依赖项，并使用 Composer PHPCS 插件注册 PHPCSDebug 标准到 PHP_CodeSniffer。

独立安装

通过您喜欢的方法安装 PHP CodeSniffer。
将 PHPCS 的路径注册到您的系统 $PATH 环境变量中，以便在文件系统的任何位置都可以使用 phpcs 命令。
下载最新 PHPCSDevTools 发布版并将其解压/解tar到任意目录。您也可以选择使用 git 克隆此仓库。
使用以下命令将您放置 PHPCSDevTools 仓库副本的目录路径添加到 PHP CodeSniffer 配置中
```
phpcs --config-set installed_paths /path/to/PHPCSDevTools
```
⚠️ 警告： installed_paths 命令会覆盖之前设置的任何 installed_paths。如果您之前已为其他外部标准设置 installed_paths，请先运行 phpcs --config-show，然后运行带有所有所需路径（以逗号分隔）的 installed_paths 命令，例如：
```
phpcs --config-set installed_paths /path/1,/path/2,/path/3
```

特性

检查 PHPCS 标准中的所有检查是否功能完整

现在您可以为标准中的每个嗅探检查是否都附带了文档XML文件（警告）以及单元测试文件（错误）。该工具还将验证标准中是否存在没有与嗅探相关联的文档或测试文件（“孤岛”文件）。

要使用该工具，请从标准仓库的根目录运行它，如下所示

# When installed as a project dependency:
vendor/bin/phpcs-check-feature-completeness

# When installed globally with Composer:
phpcs-check-feature-completeness

# When installed as a git clone or otherwise:
php -f "path/to/PHPCSDevTools/bin/phpcs-check-feature-completeness"

如果一切正常，您将看到以下消息

All # sniffs are accompanied by unit tests and documentation.
No orphaned documentation or test files found.

如果缺少文件，您将看到每个缺失文件的错误/警告，如下所示

WARNING: Documentation missing for path/to/project/StandardName/Sniffs/Category/SniffNameSniff.php.
ERROR: Unit tests missing for path/to/project/StandardName/Sniffs/Category/SniffNameSniff.php.

如果找到孤岛文件，您将收到每个孤岛文件的警告，如下所示

WARNING: Orphaned documentation file found path/to/project/StandardName/Docs/Category/NonExistantSniffStandard.xml.
WARNING: Orphaned test file found path/to/project/StandardName/Test/Category/NonExistantSniffUnitTest.inc.

为了获得最快的结果，建议将标准所在的子目录名称传递给脚本，如下所示

phpcs-check-feature-completeness ./StandardName

选项

directories <dir>     One or more specific directories to examine.
                      Defaults to the directory from which the script is run.
-q, --quiet           Turn off warnings for missing documentation and orphaned
                      files.
                      Equivalent to running with "--no-docs --no-orphans".
--exclude=<dir1,dir2> Comma-delimited list of (relative) directories to
                      exclude from the scan.
                      Defaults to excluding the /vendor/ directory.
--no-docs             Disable missing documentation check.
--no-orphans          Disable orphaned files check.
--no-progress         Disable progress in console output.
--colors              Enable colors in console output.
                      (disables auto detection of color support).
--no-colors           Disable colors in console output.
-v                    Verbose mode.
-h, --help            Print this help.
-V, --version         Display the current version of this script.

检查调试

一旦安装了此项目，在运行 phpcs -i 时，您将在安装的标准列表中看到一个新的 PHPCSDebug 规则集。

目前，此标准仅包含一个嗅探：PHPCSDebug.Debug.TokenList。此嗅探将显示（测试用例）文件中找到的标记的紧凑但详细的信息。

此嗅探与PHPCS 3.1.0+兼容。

典型用法

为要编写的新的嗅探设置测试用例文件。
使用此标准在测试用例文件上运行PHPCS，以查看文件中找到的标记列表

phpcs ./SniffNameUnitTest.inc --standard=PHPCSDebug

或与您正在开发的新的嗅探一起使用

phpcs ./SniffNameUnitTest.inc --standard=YourStandard,PHPCSDebug --sniffs=YourStandard.Category.NewSniffName,PHPCSDebug.Debug.TokenList

输出将类似于以下内容

Ptr | Ln | Col  | Cond | ( #) | Token Type                 | [len]: Content
-------------------------------------------------------------------------
  0 | L1 | C  1 | CC 0 | ( 0) | T_OPEN_TAG                 | [  5]: <?php

  1 | L2 | C  1 | CC 0 | ( 0) | T_WHITESPACE               | [  0]:

  2 | L3 | C  1 | CC 0 | ( 0) | T_COMMENT                  | [ 32]: // Boolean not operator: All OK.

  3 | L4 | C  1 | CC 0 | ( 0) | T_IF                       | [  2]: if
  4 | L4 | C  3 | CC 0 | ( 0) | T_WHITESPACE               | [  1]: ⸱
  5 | L4 | C  4 | CC 0 | ( 0) | T_OPEN_PARENTHESIS         | [  1]: (
  6 | L4 | C  5 | CC 0 | ( 1) | T_WHITESPACE               | [  1]: ⸱
  7 | L4 | C  6 | CC 0 | ( 1) | T_CONSTANT_ENCAPSED_STRING | [  4]: 'bb'
  8 | L4 | C 10 | CC 0 | ( 1) | T_WHITESPACE               | [  1]: ⸱
  9 | L4 | C 11 | CC 0 | ( 1) | T_IS_NOT_IDENTICAL         | [  3]: !==
 10 | L4 | C 14 | CC 0 | ( 1) | T_WHITESPACE               | [  1]: ⸱
 11 | L4 | C 15 | CC 0 | ( 1) | T_CONSTANT_ENCAPSED_STRING | [  4]: 'bb'
 12 | L4 | C 19 | CC 0 | ( 1) | T_WHITESPACE               | [  1]: ⸱
 13 | L4 | C 20 | CC 0 | ( 0) | T_CLOSE_PARENTHESIS        | [  1]: )
 14 | L4 | C 21 | CC 0 | ( 0) | T_WHITESPACE               | [  1]: ⸱
 15 | L4 | C 22 | CC 0 | ( 0) | T_OPEN_CURLY_BRACKET       | [  1]: {
 16 | L4 | C 23 | CC 0 | ( 0) | T_WHITESPACE               | [  0]:

 17 | L5 | C  1 | CC 0 | ( 0) | T_WHITESPACE               | [  1]: →
 18 | L5 | C  2 | CC 0 | ( 0) | T_IF                       | [  2]: if
 19 | L5 | C  4 | CC 0 | ( 0) | T_WHITESPACE               | [  1]: ⸱
 20 | L5 | C  5 | CC 0 | ( 0) | T_OPEN_PARENTHESIS         | [  1]: (
 21 | L5 | C  6 | CC 0 | ( 0) | T_WHITESPACE               | [  0]:

PHPCS本身也可以使用-vv或-vvv详细性标志显示类似信息，然而，使用这些标志时，您将收到大量的信息，而不仅仅是标记列表，尽管这对于调试PHPCS本身很有用，但额外的信息在开发嗅探时主要是噪音。

文档 XSD 验证

此项目包含一个XML模式定义（XSD），以便对PHPCS文档XML文件进行验证。遵循XSD将确保在使用PHPCS --generator选项时，您的文档可以正确显示。

为了使用它，您需要将模式相关属性添加到嗅探文档文件的documentation元素中，如下所示

<documentation
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
    title="Name of the sniff"
>

如果您的IDE或编辑器支持XML文件的自动验证，您将收到通知，如果您的文档XML文件具有正确的元素数量、正确的类型以及某些属性的数目和标题长度等。

对XSD进行验证您的文档

您可以使用xmllint将PHPCS XML文档与XSD文件进行验证。如果已安装xmllint，则此验证可以在本地运行，也可以在CI（持续集成）中运行。

GitHub Actions CI的工作流程作业示例如下

jobs:
  validate-xml:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install xmllint
        run: |
          sudo apt-get update
          sudo apt-get install --no-install-recommends -y libxml2-utils

      # A Composer install is needed to have a local copy of the XSD available.
      - run: composer install

      - name: Validate docs against schema
        run: xmllint --noout --schema vendor/phpcsstandards/phpcsdevtools/DocsXsd/phpcsdocs.xsd ./YourRuleset/Docs/**/*Standard.xml

👉 您需要将命令中的YourRuleset替换为您的规则集名称（当然）。

贡献

欢迎为此项目做出贡献。克隆此存储库，从develop分支，进行更改，提交更改并提交拉取请求。

如果不确定您提出的更改是否受欢迎，请先打开一个问题来讨论您的建议。

许可

此代码在GNU Lesser General Public License (LGPLv3)下发布。

phpcsstandards / phpcsdevtools

维护者

详细信息