README

注意

本包是现在已废弃的由 Squizlabs 创建的 PHP_CodeSniffer 包的官方延续。

关于

PHP_CodeSniffer 是一组两个 PHP 脚本；主要的 phpcs 脚本用于对 PHP、JavaScript 和 CSS 文件进行分词，以检测违反定义的编码标准，第二个 phpcbf 脚本用于自动纠正编码标准违规。PHP_CodeSniffer 是一个重要的开发工具，确保你的代码保持整洁和一致。

需求

PHP_CodeSniffer 需要 PHP 版本 5.4.0 或更高版本，尽管个别 sniff 可能需要额外的需求，如外部应用程序和脚本。有关这些需求列表，请参阅 配置选项手册页。

如果你将 PHP_CodeSniffer 作为团队的一部分使用，或者你在 CI 服务器上运行它，你可能想使用配置文件 配置你的项目设置。

安装

开始使用 PHP_CodeSniffer 的最简单方法是下载每个命令的 Phar 文件

# Download using curl
curl -OL https://phars.phpcodesniffer.com/phpcs.phar
curl -OL https://phars.phpcodesniffer.com/phpcbf.phar

# Or download using wget
wget https://phars.phpcodesniffer.com/phpcs.phar
wget https://phars.phpcodesniffer.com/phpcbf.phar

# Then test the downloaded PHARs
php phpcs.phar -h
php phpcbf.phar -h

这些 Phar 文件使用 PHPCS 的官方发布密钥签名，指纹为 689D AD77 8FF0 8760 E046 228B A978 2203 05CD 5C32。

截至 PHP_CodeSniffer 3.10.3，可以通过使用 GitHub Artifact Attestations 和 GitHub CLI 工具 的以下命令验证与发布关联的 PHAR 文件的来源： gh attestation verify [phpcs|phpcbf].phar -o PHPCSStandards。

Composer

如果你使用 Composer，可以使用以下命令全局安装 PHP_CodeSniffer

composer global require "squizlabs/php_codesniffer=*"

确保你的 composer bin 目录在 PATH 中。默认值为 ~/.composer/vendor/bin/，但你可以通过运行 composer global config bin-dir --absolute 检查你需要使用的值。

或者，你可以在 composer.json 文件中包含对 squizlabs/php_codesniffer 的依赖。例如

{
    "require-dev": {
        "squizlabs/php_codesniffer": "^3.0"
    }
}

然后你将能够从 vendor bin 目录中运行 PHP_CodeSniffer

./vendor/bin/phpcs -h
./vendor/bin/phpcbf -h

Phive

如果你使用 Phive，可以使用以下命令将 PHP_CodeSniffer 作为项目工具安装

phive install --trust-gpg-keys 689DAD778FF08760E046228BA978220305CD5C32 phpcs
phive install --trust-gpg-keys 689DAD778FF08760E046228BA978220305CD5C32 phpcbf

然后你将能够从 tools 目录中运行 PHP_CodeSniffer

./tools/phpcs -h
./tools/phpcbf -h

Git Clone

你也可以下载 PHP_CodeSniffer 源代码，并直接从 Git 克隆运行 phpcs 和 phpcbf 命令

git clone https://github.com/PHPCSStandards/PHP_CodeSniffer.git
cd PHP_CodeSniffer
php bin/phpcs -h
php bin/phpcbf -h

入门指南

PHP_CodeSniffer 使用的默认编码标准是 PEAR 编码标准。要检查文件是否违反 PEAR 编码标准，只需指定文件的路径

phpcs /path/to/code/myfile.php

或者，如果你想检查整个目录，你可以指定目录的位置而不是文件。

phpcs /path/to/code-directory

如果你希望将代码与 PSR-12 编码标准进行比较，请使用 --standard 命令行参数

phpcs --standard=PSR12 /path/to/code-directory

如果PHP_CodeSniffer检测到任何编码标准错误，运行命令后会显示报告。

完整的使用信息和示例报告可在使用页面找到。

文档

PHP_CodeSniffer的文档可在GitHub wiki上找到。

问题

错误报告和功能请求可提交至GitHub Issue Tracker。

贡献

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

版本控制

PHP_CodeSniffer使用MAJOR.MINOR.PATCH版本号格式。

当对phpcs或phpcbf命令的使用方式、ruleset.xml格式或sniff开发者使用的API进行不兼容的更改时，会增加MAJOR版本号；或者删除自定义PHP_CodeSniffer令牌类型，或者完全从PHP_CodeSniffer中删除现有的sniff。

• 当进行不兼容的更改时，例如：
• 更改了phpcs或phpcbf命令的使用方式；
• 更改了ruleset.xml格式；
• 更改了sniff开发者使用的API；
• 删除了自定义PHP_CodeSniffer令牌类型；

从PHP_CodeSniffer中删除了现有的sniff。

• 增加MINOR版本号的情况包括：
• 向phpcs和phpcbf命令添加了向后兼容的新功能；
• 对ruleset.xml格式、sniff开发者使用的API或包含的标准的sniff进行了向后兼容的更改；
• 向包含的标准添加了新的sniff；
• 从包含的标准中删除了现有的sniff。

注意：对sniff开发者使用的API的向后兼容更改将允许现有的sniff继续运行而不产生致命错误，但可能不会导致sniff报告与之前相同的错误，除非需要进行更改。

增加PATCH版本号的情况包括：

• 进行了向后兼容的错误修复。

注意：由于PHP_CodeSniffer旨在报告和修复问题，大多数错误都是由于编码标准错误被错误报告或应报告的编码标准错误未报告而导致的。这意味着PHP_CodeSniffer产生的消息和它所做的修复可能在PATCH版本之间有所不同。