README

PHPCompatibilityParagonie

使用 PHPCompatibilityParagonie，您可以使用 Paragonie polyfills 分析项目的代码库，以实现 PHP 交叉版本兼容性。

此仓库包含什么？

两组 PHP_CodeSniffer 规则集，用于检查项目中 PHP 交叉版本兼容性问题，同时考虑到 Paragonie polyfill 库提供的 polyfills。

这些规则集通过排除由这些库提供的回填和 polyfills，防止了来自 PHPCompatibility 标准的误报。

注意：由于 sodium_compat 库以 random_compat 作为依赖项，因此 PHPCompatibilityParagonieSodiumCompat 规则集包括 PHPCompatibilityParagonieRandomCompat 规则集。

在实践中，这意味着如果您的项目同时使用这两个库，您只需要使用 PHPCompatibilityParagonieSodiumCompat 规则集来防止两者都出现误报。

要求

• PHP_CodeSniffer.

  • PHP 5.3+ 用于与 PHP_CodeSniffer 2.3.0+ 一起使用。
  • PHP 5.4+ 用于与 PHP_CodeSniffer 3.0.2+ 一起使用。

  为了获得最佳结果，请使用 PHP_CodeSniffer 的最新稳定版本。PHP_CodeSniffer 的最低推荐版本是 2.6.0。

• PHPCompatibility 9.0.0+.

安装说明

唯一支持的安装方法是通过 Composer。

如果您还没有安装用于管理 PHP_CodeSniffer 的 installed_paths 设置的 Composer 插件，请从命令行运行以下命令

composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer require --dev dealerdirect/phpcodesniffer-composer-installer:"^0.7" phpcompatibility/phpcompatibility-paragonie:"*"

如果您已经安装了 Composer PHP_CodeSniffer 插件，请运行

composer require --dev phpcompatibility/phpcompatibility-paragonie:"*"

接下来，运行

vendor/bin/phpcs -i

如果一切顺利，您现在将看到为 PHP_CodeSniffer 安装了 PHPCompatibility、PHPCompatibilityParagonieRandomCompat 和 PHPCompatibilityParagonieSodiumCompat 标准。

如何使用

现在您可以使用以下命令检查项目中的代码以实现 PHP 交叉版本兼容性

./vendor/bin/phpcs -p . --standard=PHPCompatibilityParagonieRandomCompat

./vendor/bin/phpcs -p . --standard=PHPCompatibilityParagonieSodiumCompat

默认情况下，您将只收到有关已弃用和/或删除的 PHP 特性的通知。

要充分利用 PHPCompatibilityParagonie 规则集，您应指定一个 testVersion 以进行检查。这将启用对已弃用/删除的 PHP 特性以及使用新 PHP 特性的代码的检测。

例如

# For a project which should be compatible with PHP 5.3 up to and including PHP 7.0:
./vendor/bin/phpcs -p . --standard=PHPCompatibilityParagonieRandomCompat --runtime-set testVersion 5.3-7.0

# For a project which should be compatible with PHP 5.4 and higher:
./vendor/bin/phpcs -p . --standard=PHPCompatibilityParagonieSodiumCompat --runtime-set testVersion 5.4-

有关设置 testVersion 的更多详细信息，请参阅通用 PHPCompatibility 标准的 README。

仅测试 PHP 文件

默认情况下，PHP_CodeSniffer 将分析 PHP、JavaScript 和 CSS 文件。由于 PHPCompatibility sniff 只针对 PHP 代码，您可以告诉 PHP_CodeSniffer 只检查 PHP 文件，从而使其运行稍微快一些，如下所示

./vendor/bin/phpcs -p . --standard=PHPCompatibilityParagonieRandomCompat --extensions=php --runtime-set testVersion 5.3-

许可证

PHPCompatibility 组织内的所有代码均根据 GNU Lesser General Public License (LGPL) 发布。有关更多信息，请访问 https://www.gnu.org/copyleft/lesser.html

变更日志

1.3.3 - 2024-04-25

• 当规则集在最新 1.x 版本的 sodium_compat polyfill 代码上运行时，防止出现新的误报。
• 现在推荐的 Composer PHPCS 插件版本是 ^1.0。
• 其他维护工作。包括来自 @fredden 的贡献。

1.3.2 - 2022-10-25

• README：更新了与 Composer >= 2.2 兼容的安装说明 https://blog.packagist.com/composer-2-2/#more-secure-plugin-execution。
• Composer：该软件包现在将自己标识为静态分析工具。感谢 @GaryJones！
• 其他维护工作和较小的文档更新。

1.3.1 - 2021-02-15

• 现在推荐的 Composer PHPCS 插件版本是 ^0.7.0，它提供了与 Composer 2.0 的兼容性。
• 规则集现在也针对 PHP 7.4 和 8.0 进行了测试。注意：仅在与 PHP_CodeSniffer >= 3.5.6 结合使用时，才提供对 PHP 7.4 的完整支持。注意：仅在与 PHP_CodeSniffer >= 3.5.7 结合使用时，才提供对 PHP 8.0 的运行时支持，预计 PHP_CodeSniffer 3.6.0 将提供完整支持。

1.3.0 - 2019-11-04

• 更新规则集，以实现与 1.12.0 版本的 sodium_compat 的完全兼容性。

1.2.0 - 2019-10-16

• 更新规则集，以实现与 1.11.0 版本的 sodium_compat 的完全兼容性。

1.1.0 - 2019-08-29

• 已更新 PHPCompatibilityParagonieSodiumCompat 规则集，以考虑 sodium_compat polyfill 的最新更改。
• 当规则集在 sodium_compat polyfill 的代码上运行时，防止出现误报。
• Composer：推荐的 Composer PHPCS 插件版本已升级至 ^0.5.0。
• CI：改进了 SodiumCompat 规则集的集成测试。
• CI：添加了由于 polyfill 库本身的更改而导致的误报的早期预警系统。

1.0.1 - 2018-12-16

• 当规则集在 random_compat polyfill 的代码上运行时，防止出现误报。
• 规则集现在也针对 PHP 7.3 进行了测试。注意：由于 PHP_CodeSniffer 内部的不兼容性，仅在与 PHP_CodeSniffer 2.9.2 或 3.3.1+ 结合使用时，才提供对 PHP 7.3 的完整支持。

1.0.0 - 2018-10-07

PHPCompatibilityParagonie 的初始版本，包含覆盖 random_compat 和 sodium_compat polyfill 库的规则集。