README

🚧

PHP_CodeSniffer 的 WordPress 编码规范

• 介绍
• 最低要求
• 安装
  • 基于项目的 Composer 安装
  • 全局 Composer 安装
  • 更新你的 WordPressCS 安装到新版本
  • 使用你的 WordPressCS 安装
• 规则集
  • 标准子集
  • 使用自定义规则集
  • 自定义嗅探器行为
  • 推荐的额外规则集
• 如何使用
  • 命令行
  • 在 IDE 中使用 PHPCS 和 WordPressCS
• 使用持续集成工具自动通过 WordPressCS 运行你的代码
• 修复错误或忽略它们
  • WordPressCS 中的工具
• 贡献
• 资金
• 许可

介绍

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

本项目需要资金。请查阅如何帮助。

最低要求

WordPress 编码规范包需要

• PHP 5.4 或更高版本，并启用以下扩展
  • 过滤器
  • libxml
  • Tokenizer
  • XMLReader
• Composer

为了获得最佳结果，建议还确保以下额外的 PHP 扩展已启用

• iconv
• 多字节字符串

安装

截至 WordPressCS 3.0.0，通过以下说明使用 Composer 进行安装是唯一支持的安装类型。

Composer 将自动安装项目依赖关系，并使用 Composer PHPCS 插件 将 WordPressCS 和其他外部标准的规则集注册到 PHP_CodeSniffer 中。

如果您是从较旧的 WordPressCS 版本升级到 3.0.0 版本，请先阅读规则集维护者和最终用户升级指南！

基于项目的 Composer 安装

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

composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer require --dev wp-coding-standards/wpcs:"^3.0"

全局 Composer 安装

或者，您可能想要全局安装此标准

composer global config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer global require --dev wp-coding-standards/wpcs:"^3.0"

更新你的 WordPressCS 安装到新版本

如果您使用上述任一命令安装了WordPressCS，您可以通过以下方式升级到新版本：

# Project local install
composer update wp-coding-standards/wpcs --with-dependencies

# Global install
composer global update wp-coding-standards/wpcs --with-dependencies

使用你的 WordPressCS 安装

使用上述任一命令安装WordPressCS后，您可以按照以下方式使用它：

# Project local install
vendor/bin/phpcs -ps . --standard=WordPress

# Global install
%USER_DIRECTORY%/Composer/vendor/bin/phpcs -ps . --standard=WordPress

专业提示：为了方便将phpcs作为全局命令使用，请使用全局安装方法，并将%USER_DIRECTORY%/Composer/vendor/bin目录的路径添加到您操作系统的PATH环境变量中。

规则集

标准子集

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

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

• WordPress - 包含项目中所有sniffs的完整集
  • WordPress-Core - WordPress核心编码标准的规则集
  • WordPress-Docs - WordPress内联文档标准的附加规则集
  • WordPress-Extra - 扩展规则集，包含推荐的最佳实践，这些最佳实践在WordPress核心编码标准中未得到充分覆盖
    • 包含WordPress-Core

使用自定义规则集

如果您需要进一步自定义项目中sniffs的选择，您可以创建一个自定义规则集文件。

当您将此文件命名为.phpcs.xml、phpcs.xml、.phpcs.xml.dist或phpcs.xml.dist时，PHP_CodeSniffer将自动在您运行CodeSniffer的目录或其父目录中查找它。如果您遵循这些命名约定，则不需要提供--standard CLI参数。

有关更多信息，请阅读有关使用默认配置文件的说明。另请参阅提供的WordPressCS phpcs.xml.dist.sample文件和PHP_CodeSniffer文档中的完整注释示例规则集。

自定义嗅探器行为

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

您可以在维基百科中找到可以更改WordPressCS sniffs的所有属性的完整列表。

WordPressCS还使用来自PHPCSExtra和PHP_CodeSniffer本身的sniffs。PHPCSExtra的README包含有关可以设置PHPCSExtra sniffs的属性的说明。有关可以设置PHP_CodeSniffer sniffs的自定义属性的信息，可以在PHP_CodeSniffer维基百科中找到。

推荐的额外规则集

PHPCompatibility

非常推荐使用PHPCompatibility规则集及其子集PHPCompatibilityWP。PHPCompatibility sniffs旨在分析您的代码以实现跨版本PHP兼容性。

PHPCompatibilityWP规则集基于PHPCompatibility，但专门定制以防止在WordPress环境中运行的项目出现误报，即核心、插件和主题。

可以将它作为单独的规则集安装并单独运行，或者将其添加到您的自定义规则集中，如下所示：

<config name="testVersion" value="7.0-"/>
<rule ref="PHPCompatibilityWP">
    <include-pattern>*\.php$</include-pattern>
</rule>

无论您以何种方式运行它，请确保您已将 testVersion 设置为运行代码审查。 testVersion 决定了您将收到哪些 PHP 版本的兼容性信息。目前推荐的设置是 7.0- 以支持与 WordPress 核心相同的 PHP 版本。

有关设置 testVersion 的更多信息，请参阅

• PHPCompatibility：对代码进行特定 PHP 版本兼容性审查
• PHPCompatibility：使用自定义规则集

变量分析

为了进行一些关于（未定义/未使用）变量的额外检查，VariableAnalysis 标准是一个方便的补充。

WordPress VIP 编码规范

对于部署到 WordPress VIP 平台的项目，建议也使用 官方 WordPress VIP 编码规范 规则集。

如何使用

命令行

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

vendor/bin/phpcs --standard=WordPress wp-load.php

将产生以下输出

--------------------------------------------------------------------------------
FOUND 6 ERRORS AND 4 WARNINGS AFFECTING 5 LINES
--------------------------------------------------------------------------------
  36 | WARNING | error_reporting() can lead to full path disclosure.
  36 | WARNING | error_reporting() found. Changing configuration values at
     |         | runtime is strongly discouraged.
  52 | WARNING | Silencing errors is strongly discouraged. Use proper error
     |         | checking instead. Found: @file_exists( dirname(...
  52 | WARNING | Silencing errors is strongly discouraged. Use proper error
     |         | checking instead. Found: @file_exists( dirname(...
  75 | ERROR   | Overriding WordPress globals is prohibited. Found assignment
     |         | to $path
  78 | ERROR   | Detected usage of a possibly undefined superglobal array
     |         | index: $_SERVER['REQUEST_URI']. Use isset() or empty() to
     |         | check the index exists before using it
  78 | ERROR   | $_SERVER['REQUEST_URI'] not unslashed before sanitization. Use
     |         | wp_unslash() or similar
  78 | ERROR   | Detected usage of a non-sanitized input variable:
     |         | $_SERVER['REQUEST_URI']
 104 | ERROR   | All output should be run through an escaping function (see the
     |         | Security sections in the WordPress Developer Handbooks), found
     |         | '$die'.
 104 | ERROR   | All output should be run through an escaping function (see the
     |         | Security sections in the WordPress Developer Handbooks), found
     |         | '__'.
--------------------------------------------------------------------------------

在 IDE 中使用 PHPCS 和 WordPressCS

维基百科wiki 包含有关设置 WordPressCS 以在您的 IDE 中工作的各种内部和外部教程的链接。

使用持续集成工具自动通过 WordPressCS 运行你的代码

• 在 GitHub Actions 中运行
• 在 Travis 中运行

修复错误或忽略它们

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

WordPressCS 中的工具

从版本 1.2.0 开始，WordPressCS 有一个特殊的审查类别 Utils。

这个审查类别包含一些工具，一般而言，只需要在代码库上运行一次，并且修复器可以被认为是 有风险的，即需要开发者非常仔细的审查才能接受这些审查所做的修复。

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

目前，WordPressCS 提供以下工具

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

贡献

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

资金

如果您想赞助 WordPressCS 的工作，您可以通过向 PHP_CodeSniffer Open Collective 捐款来做到这一点。

许可

请参阅 LICENSE（MIT）。