README

🚧

• 特性
• 最低要求
• 在您的外部PHPCS标准中集成PHPCSUtils
  • 基于Composer的
  • 非Composer集成
• 常见问题解答
• 来自您的最终用户的潜在支持问题
• 贡献
• 许可协议

特性

PHPCSUtils 是一组辅助开发PHP_CodeSniffer (或简称“PHPCS”)嗅探器的工具。

本包提供以下功能

用于PHP_CodeSniffer的日益增长的实用函数

无论您需要将数组拆分为单独的项目，还是在尝试确定哪些变量被分配到list()中，或者正在确定一个函数是否有DocBlock，PHPCSUtils都能满足您的需求！

包括PHPCS原生实用函数的改进版本以及大量新实用函数。

这些函数与PHPCS 3.10.0至PHPCS master版本兼容。

一组常用的静态属性和方法

收集了用于嗅探的常用相关标记。这些是PHPCS原生PHP_CodeSniffer\Util\Tokens类提供的“标记组”的补充。

几个抽象嗅探器类，您可以在其中扩展您的嗅探器

这些类为一些常见的嗅探器类型减少了大部分工作量。

测试工具

一个抽象的UtilityMethodTestCase类，用于测试为PHP_CodeSniffer编写的实用方法。支持PHPUnit 4.x至11.x。

使用最新的PHP_CodeSniffer原生实用函数

通常，为了使用PHP_CodeSniffer原生实用函数的最新版本，您必须提高您的外部PHPCS标准的最低要求。

现在您不再需要这样做。此包允许您在PHPCS 3.10.0及更高版本的PHP_CodeSniffer所有版本中使用这些实用函数的最新版本。

完全文档化

要查看所有可用抽象嗅探器、实用函数和PHPCS辅助函数的详细信息，请阅读全面文档。

最低要求

• PHP 5.4或更高版本。
• PHP_CodeSniffer 3.10.0+.
• 推荐用于最佳功能的PHP扩展
  • PCRE具有Unicode支持（通常默认启用）

在您的外部PHPCS标准中集成PHPCSUtils

基于Composer的

如果你的外部PHP_CodeSniffer标准仅支持Composer安装，集成PHPCSUtils相当简单。

在您的外部PHPCS标准项目的根目录中运行以下命令

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

无需进一步操作。您可以直接使用所有实用函数、抽象嗅探器类和其他PHPCSUtils功能。

ℹ️ PHPCSUtils包包括Composer PHPCS插件。

此插件将自动将PHPCSUtils（和您的外部标准）注册到PHP_CodeSniffer中，因此您和您的用户不必再为此担心。

⚠️ 注意：如果您的最终用户安装说明包括添加Composer PHPCS插件或使用--config-set installed_paths命令手动将标准注册到PHPCS的说明，您可以删除这些说明，因为它们不再需要。

ℹ️ 截至Composer 2.2，Composer将请求权限以允许Composer PHPCS插件执行代码。为了使插件功能正常，需要授予权限。这可以通过在安装标准之前指示您的用户运行以下命令来实现

composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true

运行单元测试

如果您的单元测试使用PHP_CodeSniffer的本地单元测试套件，那就没问题。

如果您有自己的单元测试套件来测试您的嗅探器，请确保在您的PHPUnit引导文件中加载Composer的vendor/autoload.php文件或作为PHPUnit引导文件。

如果您打算使用PHPCSUtils/TestUtils目录中提供的测试工具，请确保在您的PHPUnit引导文件中同时加载vendor/phpcsstandards/phpcsutils/phpcsutils-autoload.php文件。

非Composer集成

在这种情况下，您需要更新最终用户的非Composer安装说明。

要使用基于非Composer的安装来设置您的嗅探器开发环境，应用相同的说明。

您基于非Composer的安装说明可能看起来像这样

• 通过您首选的方法安装PHP_CodeSniffer。

• 将PHPCS的路径注册到系统$PATH环境变量中，以便从文件系统的任何位置执行phpcs命令。

• 下载[YourStandardName的最新版本]并将其解压/解tar到任意目录。您也可以选择使用git克隆仓库。

• 使用以下命令将您放置YourStandardName仓库副本的目录路径添加到PHP_CodeSniffer配置中

  phpcs --config-set installed_paths /path/to/YourStandardName

  警告：⚠️ installed_paths命令会覆盖之前设置的任何installed_paths。如果您之前为其他外部标准设置了installed_paths，请首先运行phpcs --config-show，然后运行带有所有路径的installed_paths命令，路径之间用逗号分隔，例如

  phpcs --config-set installed_paths /path/1,/path/2,/path/3

为了在将PHPCSUtils添加到您的标准时保持正常工作，您需要将最后一项替换为以下内容

• 接下来，下载最新的PHPCSUtils版本并将其解压/解tar到任意目录。您也可以选择使用git克隆仓库。

• 将您放置 YourStandardName 仓库和 PHPCSUtils 仓库的路径添加到 PHP_CodeSniffer 配置中，可以使用以下命令

  phpcs --config-set installed_paths /path/to/YourStandardName,/path/to/PHPCSUtils

  警告：⚠️ installed_paths命令会覆盖之前设置的任何installed_paths。如果您之前为其他外部标准设置了installed_paths，请首先运行phpcs --config-show，然后运行带有所有路径的installed_paths命令，路径之间用逗号分隔，例如

  phpcs --config-set installed_paths /path/1,/path/2,/path/3

运行单元测试

为了支持运行嗅探单元测试的非 Composer 安装，您需要调整 PHPUnit 的 bootstrap.php 文件，以便传递一个指向您的 PHPCSUtils 安装的环境外部变量。

// Get the PHPCS dir from an environment variable.
$phpcsUtilDir = getenv('PHPCSUtils_DIR');

// This may be a Composer install.
if ($phpcsUtilDir === false && file_exists(__DIR__ . '/vendor/autoload.php')) {
    $vendorDir    = __DIR__ . '/vendor';
    $phpcsUtilDir = $vendorDir . '/phpcsstandards/phpcsutils';

    // Load the Composer autoload file.
    require_once $vendorDir . '/autoload.php';

    // This snippet is only needed when you use the PHPCSUtils TestUtils.
    if (file_exists($phpcsUtilDir . '/phpcsutils-autoload.php')) {
        require_once $phpcsUtilDir . '/phpcsutils-autoload.php';
    }

} elseif ($phpcsUtilDir !== false) {
    $phpcsUtilDir = realpath($phpcsUtilDir);

    require_once $phpcsUtilDir . '/phpcsutils-autoload.php';
} else {
    echo 'Uh oh... can\'t find PHPCSUtils.

If you use Composer, please run `composer install`.
Otherwise, make sure you set a `PHPCSUtils_DIR` environment variable in your phpunit.xml file
pointing to the PHPCS directory.
';

    die(1);
}

完成这些后，您需要对自己的开发环境进行小的调整，以便在非 Composer 安装中运行单元测试

• 将您项目的 phpunit.xml.dist 文件复制到 phpunit.xml。

• 在 phpunit.xml 文件中的 <phpunit> 标签内添加以下内容，将 /path/to/PHPCSUtils 替换为在您的本地系统上安装 PHPCSUtils 的路径

  <php>
      <env name="PHPCSUtils_DIR" value="/path/to/PHPCSUtils"/>
  </php>

常见问题解答

问：在没有外部标准需要注册自动加载器的情况下，这一切是如何工作的？

答：由于 PHPCSUtils 已与 PHPCS 注册为外部标准，并且 PHPCSUtils 符合 PHPCS 的命名要求，因此 PHPCS 的本地自动加载器将自动处理从 PHPCSUtils 加载的类。

问：使用 PHPCSUtils 是否会影响 PHPCS 的原生嗅探器？

答：不会。PHPCSUtils 只会对明确使用 PHPCSUtils 功能的嗅探器起作用。

如果您的标准包括 PHPCS 的原生嗅探器和您自己的嗅探器，您的嗅探器可以从 PHPCSUtils 提供的向后兼容层和额外的实用函数中受益。然而，PHPCS 的原生嗅探器不会收到这些好处，因为 PHPCS 本身并不使用 PHPCSUtils。

问：这些实用工具与 JavaScript/CSS 文件兼容吗？

答：在 PHPCS 4.x 中将从 PHP_CodeSniffer 中移除 JS/CSS 支持。虽然目前一些实用工具 可能 与 JS/CSS 文件一起工作，但 PHPCSUtils 不提供对 PHP_CodeSniffer 的 JS/CSS 嗅探的正式支持，并在 PHPCS 4.x 发布后将停止任何现有支持。

问：是否支持所有文件编码？

答：不是的。UTF-8 文件编码是唯一官方支持的编码。对其他编码的支持可能偶然有效，但不是官方支持。

建议用户将文件保存为 UTF-8 编码以获得最佳效果。

注意：PHP_CodeSniffer 3.x 默认期望文件编码为 UTF-8。

来自您的最终用户的潜在支持问题

问：用户报告了一个来自 PHPCSUtils 的“类未找到”的致命错误。

1. 检查用户安装的 PHPCSUtils 版本是否符合您标准所需的 PHPCSUtils 的最低版本。如果不是，他们需要升级。
2. 如果版本正确，这表明最终用户没有安装并/或注册 PHPCSUtils。
   • 请检查您标准的安装说明，确保按照这些说明操作时将安装 PHPCSUtils。
   • 请用户安装 PHPCSUtils 并将其注册到 PHP_CodeSniffer。

💡 专业提示：如果您想防止致命错误并显示一个更友好的错误消息，请将 <rule ref="PHPCSUtils"/> 添加到您标准的 ruleset.xml 文件中。

有了这个，如果 PHPCSUtils 缺失，在规则集加载完成后，PHP_CodeSniffer 将显示一个 "ERROR: "PHPCSUtils" 编码标准未安装"。 消息。

💡 专业提示：为最终用户提供升级说明。对于基于 Composer 的安装，它们应该看起来像这样

composer update your/cs-package --with-[all-]dependencies

这样，当用户更新您的编码标准包时，他们将自动更新 PHPCSUtils。

贡献

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

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

许可协议

此代码遵循GNU Lesser General Public License (LGPLv3)许可协议发布。