README

这是一个用于检查 PHP 跨版本兼容性的 PHP_CodeSniffer 嗅探器集。它将允许您分析您的代码与更高和更低版本的 PHP 的兼容性。

PHP 版本支持
需求
谢谢
升级到 PHPCompatibility 9.0.0
在 Composer 项目中安装（方法 1）
通过 git 检出安装到任意目录（方法 2）
检查您的代码与特定 PHP 版本的兼容性
- 使用框架/CMS/polyfill 特定规则集
使用自定义规则集
- 规则集中的 testVersion 与命令行
- PHPCompatibility 特定选项
扩展 PHPCompatibility 的项目
贡献
许可证

PHP 版本支持

该项目旨在涵盖自 PHP 5.0 以来引入的所有 PHP 兼容性更改，直至最新版本的 PHP。这是一个持续的过程，覆盖范围尚未达到 100%（如果，确实能够达到）。进展情况可在我们的 GitHub 问题跟踪器上跟踪。

欢迎提交拉取请求，以检查 PHP 4 代码中的兼容性问题 - 特别是 PHP 4 和 PHP 5.0 之间的兼容性问题。尽管如此，由于目前尚未积极开发此类嗅探器，因此引入 PHP 5.1 之前的变化的覆盖范围仍将不完整。

需求

PHP 5.4+
PHP CodeSniffer: 3.10.0+.

嗅探器被设计为在不同版本的 PHP 上运行 PHP CodeSniffer 时都能提供相同的结果。您应该在不考虑测试环境中使用的 PHP 版本的情况下获得一致的结果，尽管为了获得最佳结果，建议在最新的 PHP 版本和最新的 PHP_CodeSniffer 版本上运行嗅探器。

自版本 8.0.0 以来，PHPCompatibility 标准还可以与 PHP CodeSniffer 3.x 一起使用。自版本 9.0.0 以来，已取消对 PHP CodeSniffer 1.5.x 和低 2.x 版本 < 2.3.0 的支持。自版本 10.0.0 以来，已取消对 PHP < 5.4 和 PHP CodeSniffer < 3.10.0 的支持。

谢谢

感谢所有贡献者的宝贵贡献。

感谢 WP Engine 在 PHP 7.0 嗅探器上的支持。

⚠️ 升级到 PHPCompatibility 9.0.0 ⚠️

此库已重新组织。所有嗅探器都已放入类别中，并且大量嗅探器已被重命名。

如果您在自定义规则集中使用完整的 PHPCompatibility 标准而不使用 exclude 指令，并且（尚未）使用在 PHP_CodeSniffer 3.2.0 中引入的新式 PHP_CodeSniffer 注释，则这不会产生明显的影响，一切应该像以前一样工作。

但是，如果您在自定义规则集中使用 exclude 指令来排除 PHPCompatibility 检查，或者使用新风格的 PHP_CodeSniffer 内联注释，在升级时需要更新这些内容。这应该是一个一次性的更改。变更日志包含了所有嗅探器重命名的详细信息。

在升级之前，请仔细阅读 9.0.0 版本的变更日志。

在 Composer 项目中安装（方法 1）

将以下行添加到您的 composer.json 文件的 require-dev 部分。

"require-dev": {
    "phpcompatibility/php-compatibility": "*"
},
"prefer-stable" : true

接下来，PHP CodeSniffer 需要知道标准的位置。
- 如果您使用的只有 PHPCompatibility 作为外部 PHP CodeSniffer 标准，您可以将以下内容添加到您的 composer.json 文件中，以自动运行必要的命令
```
"scripts": {
    "post-install-cmd": "\"vendor/bin/phpcs\" --config-set installed_paths vendor/phpcompatibility/php-compatibility",
    "post-update-cmd" : "\"vendor/bin/phpcs\" --config-set installed_paths vendor/phpcompatibility/php-compatibility"
}
```
- 或者 - 如果您使用多个外部 PHP CodeSniffer 标准，强烈建议您使用以下任何 Composer 插件来处理这个问题。
  
  只需将您喜欢的 Composer 插件添加到您的 composer.json 文件的 require-dev 部分。
  - DealerDirect/phpcodesniffer-composer-installer:"^0.6.0"
  - higidi/composer-phpcodesniffer-standards-plugin
  - SimplyAdmire/ComposerPlugins。这个插件可能仍然有效，但似乎已被废弃。
- 如果使用自定义规则集，作为最后的替代方案，您可以通过将以下片段添加到您的自定义规则集中来告诉 PHP CodeSniffer PHPCompatibility 标准的路径
```
<config name="installed_paths" value="vendor/phpcompatibility/php-compatibility" />
```
运行 composer update --lock 以安装 PHP CodeSniffer、PHPCompatibility 编码标准以及 - 可选的 - Composer 插件。
通过在命令行中运行 ./vendor/bin/phpcs -i 验证 PHPCompatibility 标准是否正确注册。PHPCompatibility 应该列在可用的标准之一。
现在您可以使用以下命令来检查您的代码
```
./vendor/bin/phpcs -p . --standard=PHPCompatibility
```

通过 git 检出安装到任意目录（方法 2）

通过您选择的方法安装 PHP CodeSniffer。

PHP CodeSniffer 提供了各种安装方法，以适应您的工作流程：Composer、PEAR、Phar 文件、zip/tar 发布存档或使用 Git 检出仓库。

技巧： 将 PHPCS 的路径注册到系统 $PATH 环境变量中，以便在文件系统的任何位置都可以使用 phpcs 命令。
下载最新的 PHPCompatibility 发布版并将其解压/解tar到任意目录。

您还可以选择使用 git 克隆仓库以轻松定期更新您的安装。
使用以下命令通过命令行将您放置 PHPCompatibility 仓库副本的目录路径添加到 PHP CodeSniffer 配置中
```
phpcs --config-set installed_paths /path/to/PHPCompatibility
```
例如，如果您将 PHPCompatibility 仓库放置在 /my/custom/standards/PHPCompatibility 目录中，您需要将此目录添加到 PHP CodeSniffer 的 installed_paths 配置变量中。

警告：⚠️ installed_paths 命令将覆盖之前设置的任何 installed_paths。如果您之前为其他外部标准设置了 installed_paths，请首先运行 phpcs --config-show，然后运行 installed_paths 命令，将所有路径用逗号分隔，例如。
```
phpcs --config-set installed_paths /path/1,/path/2,/path/3
```
小技巧： 如果您使用自定义规则集，可以通过将以下片段添加到自定义规则集中来告诉PHP CodeSniffer PHPCompatibility标准（s）的路径
```
<config name="installed_paths" value="/path/to/PHPCompatibility" />
```
通过在命令行上运行 phpcs -i 来验证PHPCompatibility标准是否正确注册。PHPCompatibility应列在可用标准之一。
现在您可以使用以下命令来检查您的代码
```
phpcs -p . --standard=PHPCompatibility
```

检查您的代码与特定 PHP 版本的兼容性

使用命令行从命令行运行编码标准： phpcs -p . --standard=PHPCompatibility。
默认情况下，您将只收到有关已弃用和/或删除的PHP特性的通知。
要充分利用PHPCompatibility标准，您应该指定一个要检查的testVersion。这将启用对已弃用/删除的PHP特性以及使用新PHP特性的代码的检测。
- 您可以通过将 --runtime-set testVersion 5.5 添加到命令行命令来仅针对特定PHP版本运行检查。
- 您还可以指定需要支持的PHP版本范围。在这种情况下，将报告影响该范围内任何PHP版本的兼容性问题：--runtime-set testVersion 5.3-5.5。
- 从PHPCompatibility 7.1.3开始，如果您想支持高于或低于特定版本的任何内容，可以省略范围的一部分，例如，使用 --runtime-set testVersion 7.0- 来运行所有PHP 7.0及以上的检查。
默认情况下，报告将发送到控制台。如果您想将报告保存到文件，请将以下内容添加到命令行命令： --report-full=path/to/report-file。有关更多信息和其他报告选项，请查看PHP CodeSniffer 维基。

使用框架/CMS/polyfill 特定规则集

截至2018年中旬，有一些针对框架/CMS特定的规则集可供使用。这些规则集托管在自己的存储库中。

PHPCompatibilityJoomla GitHub | Packagist
PHPCompatibilityWP GitHub | Packagist

从2018年秋季开始，还有一些针对PHP polyfill特定的规则集可用

PHPCompatibilityPasswordCompat GitHub | Packagist：考虑了@ircmaxell的password_compat polyfill库。
PHPCompatibilityParagonie GitHub | Packagist：包含两个规则集，分别考虑了Paragonie的random_compat和sodium_compat polyfill库。
PHPCompatibilitySymfony GitHub | Packagist：包含多个规则集，考虑了Symfony项目提供的各种PHP polyfill库。有关可用的规则集的更多详细信息，请查看PHPCompatibilitySymfony存储库的README。

如果您想确保在任何时候都拥有所有PHPCompatibility规则集，您可以使用PHPCompatibilityAll软件包 GitHub | Packagist。

重要： 框架/内容管理系统/补丁特定规则集不会为您的项目设置最小PHP版本，因此您仍需要传递一个testVersion以获得最准确的结果。

使用自定义规则集

就像任何PHP CodeSniffer标准一样，您可以将PHPCompatibility添加到自定义的PHP CodeSniffer规则集中。

<?xml version="1.0"?>
<ruleset name="Custom ruleset">
    <description>My rules for PHP CodeSniffer</description>

    <!-- Run against the PHPCompatibility ruleset -->
    <rule ref="PHPCompatibility"/>

    <!-- Run against a second ruleset -->
    <rule ref="PSR2"/>

</ruleset>

您还可以在规则集中设置testVersion。

    <!-- Check for cross-version support for PHP 5.6 and higher. -->
    <config name="testVersion" value="5.6-"/>

当然，也支持其他高级选项，如更改特定sniffs的消息类型或严重性，这些选项在PHPCS Annotated ruleset 维基页面上有描述。

规则集中的 `testVersion` 与命令行

在PHPCS 3.2.0及以下版本中，一旦在规则集中设置了testVersion，您就无法再从命令行覆盖它。从PHPCS 3.3.0版本开始，通过命令行设置的testVersion将覆盖规则集中的testVersion。

这允许在需要遵守PHP 5.5- 但有一个需要与PHP 5.2- 兼容的引导文件的项目时，具有更大的灵活性。

PHPCompatibility 特定选项

目前，有两个sniffs具有可以通过规则集设置的属性。将来可能会有更多自定义属性可用。

PHPCompatibility.Extensions.RemovedExtensions sniffs检查基于用于这些扩展的功能前缀删除的扩展。这可能与使用相同功能前缀的用户空间函数冲突。

要使白名单用户空间函数，可以向sniffs传递一个以逗号分隔的函数名列表。

    <!-- Whitelist the mysql_to_rfc3339() and mysql_another_function() functions. -->
    <rule ref="PHPCompatibility.Extensions.RemovedExtensions">
        <properties>
            <property name="functionWhitelist" type="array" value="mysql_to_rfc3339,mysql_another_function"/>
        </properties>
    </rule>

PHPCompatibility.Interfaces.RemovedSerializable sniffs需要了解所有扩展Serializable接口的接口，以提供最可靠的结果。当sniffs遇到一个未知的sniffs扩展Serializable接口的接口时，将发出警告，并建议将接口名称添加到属性中。

要告知sniffs有关提供Serializable接口的附加接口，请将以下示例代码片段添加到自定义规则集中

    <rule ref="PHPCompatibility.Interfaces.RemovedSerializable">
        <properties>
            <property name="serializableInterfaces" type="array">
                <element value="MyCustomSerializableInterface"/>
                <element value="AnotherSerializableInterface"/>
            </property>
        </properties>
    </rule>

扩展 PHPCompatibility 的项目

有数百个公共项目使用PHPCompatibility或在此基础上扩展。以下是一些您可能知道或可以查看的项目列表

adamculp/php-code-quality - 一个执行大量代码质量检查的Docker镜像
VFAC/PHP7Compatibility - 一个检查PHP7兼容性的Docker容器
grumphp-php-compatibility - GrumPHP的插件
PHPCompatibility Checker WordPress插件： Wordpress站点和 Github
WordPress Tide项目
PHPStorm内置了对PHPCompatibility的支持
Moodle codechecker - 一个用于Moodle 编码风格（包括PHPCompatibility）的插件
Github Action - 一个在您的源代码上运行此PHPCS标准的Github Action

贡献

非常欢迎贡献。请阅读CONTRIBUTING文档以开始。

许可证

此代码遵循GNU Lesser General Public License（LGPL）发布。有关更多信息，请访问http://www.gnu.org/copyleft/lesser.html

phpcompatibility / php-compatibility

维护者

详细信息

README

PHP 版本支持

需求

谢谢

⚠️ 升级到 PHPCompatibility 9.0.0 ⚠️

在 Composer 项目中安装（方法 1）

通过 git 检出安装到任意目录（方法 2）

检查您的代码与特定 PHP 版本的兼容性

使用框架/CMS/polyfill 特定规则集

使用自定义规则集

规则集中的 `testVersion` 与命令行

PHPCompatibility 特定选项

扩展 PHPCompatibility 的项目

贡献

许可证

phpcompatibility / php-compatibility

维护者

详细信息

README

PHP 版本支持

需求

谢谢

⚠️ 升级到 PHPCompatibility 9.0.0 ⚠️

在 Composer 项目中安装（方法 1）

通过 git 检出安装到任意目录（方法 2）

检查您的代码与特定 PHP 版本的兼容性

使用框架/CMS/polyfill 特定规则集

使用自定义规则集

规则集中的 testVersion 与命令行

PHPCompatibility 特定选项

扩展 PHPCompatibility 的项目

贡献

许可证

规则集中的 `testVersion` 与命令行