README

这是一组用于PHP CodeSniffer的sniffs，用于检查PHP跨版本兼容性。它将允许您分析您的代码与更高或更低版本的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之间的兼容性问题。尽管如此，由于目前没有积极开发此类sniffs，因此引入PHP 5.1之前的变化的覆盖范围仍然不完整。

要求

PHP 5.4+
PHP CodeSniffer: 3.10.0+。

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

从版本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 sniffs的支持。

⚠️ 升级到PHPCompatibility 9.0.0 ⚠️

该库已重新组织。所有sniffs都已按类别放置，并且许多sniffs已被重命名。

如果您在自定义规则集中使用完整的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 标准（的）路径
```
<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年中旬，有一些框架/内容管理系统特定的规则集可用。这些规则集托管在自己的仓库中。

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。

重要：框架/内容管理系统/Polyfill特定的规则集不会为您的项目设置最低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 sniff检查基于这些扩展使用的函数前缀删除的扩展。这可能会与使用相同函数前缀的用户函数冲突。

要白名单用户函数，可以向sniff传递以逗号分隔的函数名称列表。

    <!-- 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 sniff需要知道所有扩展自Serializable接口的接口，以提供最可靠的结果。当sniff遇到一个它所不知道的扩展自Serializable接口的接口时，将发出警告，并建议将接口名称添加到属性中。

要通知sniff有关提供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 - 一个包括PHPCompatibility在内的Moodle 编码风格插件
Github Action - 一个在您的源代码上运行此PHPCS标准的Github Action

贡献

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

许可证

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

wimg / php-compatibility

维护者

详细信息

README

支持的PHP版本

要求

感谢

⚠️ 升级到PHPCompatibility 9.0.0 ⚠️

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

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

针对特定PHP版本进行代码兼容性检查

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

使用自定义规则集

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

PHPCompatibility特定选项

扩展PHPCompatibility的项目

贡献

许可证

wimg / php-compatibility

维护者

详细信息

README

支持的PHP版本

要求

感谢

⚠️ 升级到PHPCompatibility 9.0.0 ⚠️

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

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

针对特定PHP版本进行代码兼容性检查

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

使用自定义规则集

规则集中的testVersion与命令行比较

PHPCompatibility特定选项

扩展PHPCompatibility的项目

贡献

许可证

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