README

🚧

PHP_CodeSniffer 的 WordPress 编码规范

简介
项目历史
安装
- 要求
- Composer
- 独立
规则集
如何使用
- 命令行
- 在 IDE 中使用 PHPCS 和 WPCS
使用 CI 工具自动运行 WPCS 代码
修复错误或忽略它们
- WPCS 中的工具
贡献
许可

简介

此项目是 PHP_CodeSniffer 规则（嗅探器）的集合，用于验证为 WordPress 开发的代码。它确保代码质量并遵守编码规范，特别是官方的 WordPress 编码规范。

项目历史

2009 年 4 月 22 日，Urban Giraffe 的原始项目被打包并发布。
2011 年 5 月，该项目被分叉，并由 Chris Adams 添加到 GitHub。
2012 年 4 月，XWP 开始投入资源开发和领导 WordPress-Core、WordPress-VIP（WordPress.com VIP）和 WordPress-Extra 的嗅探器和规则集。
2015 年 5 月，首次文档规则集作为 WordPress-Docs 被添加。
2015 年，J.D. Grimes 开始做出重大贡献，同时 Gary Jones 负责维护。
2016 年，Juliette Reinders Folmer 开始大量贡献，一年内提交的代码比 GitHub 上该项目添加以来的五年中任何人都多。
2018 年 7 月，项目版本 1.0.0 发布。

安装

要求

WordPress 编码规范要求 PHP 5.4 或更高版本和 PHP_CodeSniffer 版本 3.7.2 或更高版本。

Composer

可以使用Composer依赖管理器安装标准。

composer create-project wp-coding-standards/wpcs --no-dev

运行此命令将执行以下操作：

将WordPress标准安装到wpcs目录。
安装PHP_CodeSniffer。
在PHP_CodeSniffer配置中注册WordPress标准。
使phpcs命令从wpcs/vendor/bin目录可用。

为了方便将phpcs作为全局命令使用，您可能需要将wpcs/vendor/bin目录的路径添加到操作系统的PATH环境变量中。

将WPCS作为依赖项安装

当在更大的项目中将WordPress编码标准作为依赖项安装时，上述提到的第3步不会自动执行。

有两个活跃维护的Composer插件可以为您处理PHP_CodeSniffer的标准的注册

强烈建议在您的项目中要求其中之一以处理PHPCS的外部标准的注册。

独立

按照其安装说明（通过Composer、Phar文件、PEAR或Git克隆）安装PHP_CodeSniffer。

请确保PHP_CodeSniffer的版本符合我们的要求，例如，如果您正在使用VVV。

克隆WordPress标准存储库

 git clone -b master https://github.com/WordPress/WordPress-Coding-Standards.git wpcs

将其路径添加到PHP_CodeSniffer配置中
```
 phpcs --config-set installed_paths /path/to/wpcs
```
技巧：作为替代，您可以通过将以下代码片段添加到您的自定义规则集来告诉PHP_CodeSnifferWordPress标准的路径
```
<config name="installed_paths" value="/path/to/wpcs" />
```

总结

cd ~/projects
git clone https://github.com/squizlabs/PHP_CodeSniffer.git phpcs
git clone -b master https://github.com/WordPress/WordPress-Coding-Standards.git wpcs
cd phpcs
./bin/phpcs --config-set installed_paths ../wpcs

然后通过您的.bashrc将~/projects/phpcs/bin目录添加到您的PATH环境变量中。

然后运行phpcs -i时，您应该会看到WordPress-Core等。

规则集

标准子集

该项目包含WordPress社区可能需要的所有sniffs的超集。如果您使用WordPress标准，您将获得所有的检查。

在调用phpcs以选择sniffs时，您可以使用以下标准名称，以满足您的需求

WordPress - 包含项目中所有sniffs的完整集合
- WordPress-Core - WordPress核心编码标准的主要规则集
- WordPress-Docs - WordPress内联文档标准的附加规则集
- WordPress-Extra - 扩展规则集，用于推荐的最佳实践，这些最佳实践在WordPress核心编码标准中没有充分涵盖
  - 包括WordPress-Core

注意：WPCS包在WPCS 2.0.0之前包含了一个WordPress-VIP规则集和相关sniffs。该WordPress-VIP规则集最初旨在帮助满足WordPress.com VIP编码要求，但已被取代。建议使用官方VIP编码标准规则集来检查代码是否符合VIP平台要求。

使用自定义规则集

如果您需要进一步自定义项目中嗅探器的选择，您可以创建一个自定义规则集文件。当您将此文件命名为 .phpcs.xml、phpcs.xml、.phpcs.xml.dist 或 phpcs.xml.dist 时，只要它位于您运行 CodeSniffer 的目录或其上层目录中，PHP_CodeSniffer 会自动找到它。如果您遵循这些命名约定，就不需要提供 --standard 参数。有关更多信息，请阅读有关使用默认配置文件的说明。另请参阅提供的 phpcs.xml.dist.sample 文件和 PHP_CodeSniffer 文档中的完整注释示例。

自定义嗅探器行为

WordPress 编码标准包含许多可配置的嗅探器。这意味着您可以通过在自定义 .phpcs.xml.dist 文件中设置属性来开启或关闭嗅探器的部分，或更改其行为。

您可以在 wiki 中找到可以更改的所有属性的完整列表。

如何使用

命令行

在给定的文件或目录上运行 phpcs 命令行工具，例如

phpcs --standard=WordPress wp-load.php

将产生以下输出

------------------------------------------------------------------------------------------
FOUND 8 ERRORS AND 10 WARNINGS AFFECTING 11 LINES
------------------------------------------------------------------------------------------
 24 | WARNING | [ ] error_reporting() can lead to full path disclosure.
 24 | WARNING | [ ] error_reporting() found. Changing configuration at runtime is rarely
    |         |     necessary.
 37 | WARNING | [x] "require_once" is a statement not a function; no parentheses are
    |         |     required
 39 | WARNING | [ ] Silencing errors is discouraged
 39 | WARNING | [ ] Silencing errors is discouraged
 42 | WARNING | [x] "require_once" is a statement not a function; no parentheses are
    |         |     required
 46 | ERROR   | [ ] Inline comments must end in full-stops, exclamation marks, or
    |         |     question marks
 46 | ERROR   | [x] There must be no blank line following an inline comment
 49 | WARNING | [x] "require_once" is a statement not a function; no parentheses are
    |         |     required
 54 | WARNING | [x] "require_once" is a statement not a function; no parentheses are
    |         |     required
 63 | WARNING | [ ] Detected access of super global var $_SERVER, probably needs manual
    |         |     inspection.
 63 | ERROR   | [ ] Detected usage of a non-validated input variable: $_SERVER
 63 | ERROR   | [ ] Missing wp_unslash() before sanitization.
 63 | ERROR   | [ ] Detected usage of a non-sanitized input variable: $_SERVER
 69 | WARNING | [x] "require_once" is a statement not a function; no parentheses are
    |         |     required
 74 | ERROR   | [ ] Inline comments must end in full-stops, exclamation marks, or
    |         |     question marks
 92 | ERROR   | [ ] All output should be run through an escaping function (see the
    |         |     Security sections in the WordPress Developer Handbooks), found
    |         |     '$die'.
 92 | ERROR   | [ ] All output should be run through an escaping function (see the
    |         |     Security sections in the WordPress Developer Handbooks), found '__'.
------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 6 MARKED SNIFF VIOLATIONS AUTOMATICALLY
------------------------------------------------------------------------------------------

在 IDE 中使用 PHPCS 和 WPCS

PhpStorm：请参阅 PhpStorm 文档中的 "PHP Code Sniffer 与 WordPress 编码标准集成"。
Sublime Text：请参阅 wiki 中的 "在 Sublime Text 中设置 WPCS"。
Atom：请参阅 wiki 中的 "在 Atom 中设置 WPCS"。
Visual Studio：请参阅 Tom McFarlin 的教程 "在 Visual Studio Code 中设置 PHP CodeSniffer"。
Eclipse 与 XAMPP：请参阅 wiki 中的 "使用 Eclipse 和 XAMPP 时设置 WPCS"。

使用 CI 工具自动运行 WPCS 代码

修复错误或忽略它们

您可以在维基百科中找到如何处理一些更常见问题的信息。

WPCS 中的工具

自1.2.0版本以来，WPCS有一个特殊的嗅探类别Utils。

此嗅探类别包含一些工具，通常情况下，这些工具只需要在代码库上运行一次，且修复器可能被视为风险，即在进行这些嗅探所做的修复之前，需要开发者非常仔细的审查。

此类别中的嗅探默认是禁用的，只能通过为每个嗅探添加一些属性通过自定义规则集来激活。

目前，WPCS提供以下工具

WordPress.Utils.I18nTextDomainFixer - 此嗅探可以替换代码库中使用的文本域。该嗅探将在I18n函数调用以及插件/主题头部中修复文本域。通过传递以下属性将激活嗅探
- old_text_domain：一个包含一个或多个（旧）需要替换的文本域名名的数组；
- new_text_domain：正确（新）的文本域名作为字符串。

贡献

请参阅CONTRIBUTING，包括有关单元测试标准的信息。

许可

请参阅LICENSE（MIT）。

lewebsimple / wpcs

维护者

详细信息