README

这是 Widgit Labs 风格指南的编码版本。我们包含了 phpcs、ESLint 和 stylelint 规则。

贡献

我们欢迎对这些规范做出贡献，并希望使贡献过程尽可能顺利。有关贡献的更多信息，请参阅 CONTRIBUTING.md 文件。

设置

每个规则集都可以通过 Composer 或 NPM 单独安装。要安装所需的规则集，请使用以下命令之一

PHPCS: composer require --dev widgitlabs/wlcs
ESLint: npx install-peerdeps --dev @widgitlabs/eslint-config@latest
stylelint: npm install --save-dev stylelint @widgitlabs/stylelint-config

使用 PHPCS

运行以下命令以运行标准检查

vendor/bin/phpcs --standard=vendor/widgitlabs/wlcs .

我们使用 DealerDirect phpcodesniffer-composer-installer 包来处理 PHPCS 中的 installed_paths，在首次安装 Widgit Labs 规则集时。如果您遇到错误，如 ERROR: Referenced sniff "WordPress-Core" does not exist，请删除 composer.lock 文件和 vendor 目录，并重新安装 Composer 依赖项。

最后的 . 指定了要测试的文件；这通常是当前目录（.），但您也可以通过指定它们来选择性地检查文件或目录。

您可以将此添加到您的 Travis YAML 文件中作为测试

script:
  - phpunit
  - vendor/bin/phpcs --standard=vendor/widgitlabs/wlcs .

排除文件

此标准包括对 .phpcsignore 文件（将来应将其集成到 phpcs 中）的特殊支持。只需在您的根目录中（从您将要运行 phpcs 的位置）放置一个 .phpcsignore 文件。

此文件的格式类似于 .gitignore 和类似文件：每行一个模式，注释行应以 # 开头，只有空白行的行将被忽略。

# Exclude our tests directory.
tests/

# Exclude any file ending with ".inc"
*\.inc

请注意，模式应与 PHP_CodeSniffer 风格相匹配：* 被转换为 .* 以便使用，但所有其他字符都像正则表达式一样工作。

模式相对于 .phpcsignore 文件所在的目录。在加载时，它们将被转换为绝对模式：例如，在 /your/dir/.phpcsignore 中的 */tests/* 将成为正则表达式 /your/dir/.*/tests/.*。 这与常规 PHP_CodeSniffer 的做法不同。

高级/扩展

如果您想添加更多规则（例如 WordPress.com VIP 特定规则）或自定义 PHPCS 默认设置，您可以创建自己的自定义标准文件（例如 phpcs.ruleset.xml）

<?xml version="1.0"?>
<ruleset>
	<!-- Files or directories to check -->
	<file>.</file>

	<!-- Path to strip from the front of file paths inside reports (displays shorter paths) -->
	<arg name="basepath" value="." />

	<!-- Set a minimum PHP version for PHPCompatibility -->
	<config name="testVersion" value="7.2-" />

	<!-- Use Widgit Labs Coding Standards -->
	<rule ref="vendor/widgitlabs/wlcs" />

	<!-- Add VIP-specific rules -->
	<rule ref="WordPress-VIP" />
</ruleset>

然后您可以在运行 phpcs 时引用此文件

vendor/bin/phpcs --standard=phpcs.ruleset.xml .

排除/禁用检查

您还可以自定义规则，以排除不适用于项目的元素

<rule ref="vendor/widgitlabs/wlcs">
	<!-- Disable ESLint -->
	<exclude name="WidgitLabs.Debug.ESLintSniff" />
</rule>

规则也可以在行内禁用。可以使用 // @codingStandardsIgnoreLine 注释禁用 phpcs 规则，并使用 /* eslint disable ... */ 注释禁用 ESLint 规则。

要了解这些代码的含义，在运行 phpcs 时指定 -s 参数，代码也会被输出。您可以指定完整的代码或部分代码以禁用错误组。

包含的检查

phpcs 标准基于 WordPress 编码标准中的 WordPress-VIP 标准，并通过自定义和添加来符合我们的风格指南。

使用 ESLint

ESLint 包包含一个 ESLint 配置，您可以使用它来验证您的 JavaScript 代码风格。虽然您可以通过 phpcs 运行 ESLint，但我们建议您直接通过 npm 安装和使用 ESLint。有关如何配置 ESLint 以使用 Widgit Labs 编码标准的更多信息，请参阅 @widgitlabs/eslint-config 包的 README。

安装完 @widgitlabs/eslint-config npm 包后，您可以简单地将自己的项目级 ESLint 文件指定为扩展 widgitlabs 配置。如果您全局安装此包（npm install -g @widgitlabs/eslint-config），您也可以通过 eslint -c widgitlabs . 从命令行直接引用配置。

或者，您可以创建自己的配置并扩展这些规则

.eslintrc

{
  "extends": "@widgitlabs"
}

使用 stylelint

stylelint 包包含一个 stylelint 配置，您可以使用它来验证您的 CSS 和 SCSS 代码风格。我们建议您直接通过 npm 安装和使用 stylelint。有关如何配置 stylelint 以使用 Widgit Labs 编码标准的更多信息，请参阅 @widgitlabs/stylelint 包的 README。

要将 Widgit Labs 规则集成到您的项目中，请添加一个 .stylelintrc 文件并扩展这些规则。您还可以添加自己的规则和覆盖以进行进一步的自定义。

{
  "extends": "@widgitlabs/stylelint-config",
  "rules": {
    ...
  }
}

widgitlabs / coding-standards

维护者

详情