PHP兼容性检查工具 —— PHPCompatibility 使用指南

一、项目介绍

PHPCompatibility 是一个用于检测PHP源码文件中对不同PHP版本之间不兼容变更的规则集。它作为PHP_CodeSniffer的一个插件运行，可以帮助开发者确保他们的代码在不同的PHP版本间能够平滑过渡。

主要特点：

• 多版本支持：覆盖自PHP 5.0到最新PHP版本之间的所有重要变化。
• 详细报告：提供详细的分析结果，包括废弃功能或新特性使用的提示。
• 定制化配置：允许通过规则集（rulesets）指定特定版本进行检查，或选择框架/CMS相关规则集。
• 集成友好：易于在持续集成环境如GitHub Actions或GrumPHP等工具中集成使用。

二、项目快速启动

本章节将指导您如何安装并启用 PHPCompatibility 规则集以分析您的PHP代码。

安装步骤：

1. 集成至Composer项目

打开终端，导航至您的项目目录下执行以下命令来安装PHP_CodeSniffer及PHPCompatibility:

composer require --dev squizlabs/php_codesniffer
composer require --dev wimg/php-compatibility

2. 运行代码风格检查

编辑phpcs.xml或.php_cs.dist配置文件（根据你使用的是哪种工具），加入下面的代码：

<ruleset name="My Ruleset">
    <!-- other rules -->
    
    <rule ref="Generic">
        <exclude name="VariableFunctions"/>
    </rule>
    
    <!-- Include the PHPCompatibility standard -->
    <rule ref="PSR2"/>
    <rule ref="PHPCompatibility"/>

</ruleset>

然后，在你的项目根目录下运行以下命令：

vendor/bin/phpcs src --standard=.php_cs.dist

或者如果你是在使用php-cs-fixer:

./vendor/bin/php-cs-fixer fix --diff --dry-run --config=.php_cs.dist .

以上命令将会扫描src目录下的PHP文件，并基于定义的标准进行编码规范检查。

测试特定PHP版本

你可以使用如下命令来测试您的代码对于具体PHP版本的兼容性：

vendor/bin/phpcs path/to/src --standard=PHPCompatibility --testVersion=7.2

上述命令将检查代码是否符合从PHP 7.2开始到目前所有版本的变化要求。

三、应用案例和最佳实践

应用案例

当开发面向多个PHP版本的软件时，PHPCompatibility是不可或缺的工具之一。例如，假设你在维护一款插件，该插件应能在PHP 7.3到8.1的所有版本上无缝运行，则可以在CI/CD流程中加入PHPCompatibility检查：

before_script:
  - composer install --no-interaction
  
script:
  - vendor/bin/phpcs --standard=PHPCompatibility --testVersion=7.3,8.1 src/
  
after_script:
  - echo "Code successfully linted"

最佳实践

• 确保所有的开发人员都遵循团队约定的编码标准，可以通过预提交hook自动运行phpcs检查。
• 在每次推送代码前执行phpcs命令防止潜在的兼容性问题导致的构建失败。

四、典型生态项目

除了PHPCompatibility本身外，还有一些其他的社区驱动项目值得探索，它们利用或扩展了PHPCompatibility的功能：

• VFAC/PHP7Compatibility - 提供了一个Docker容器用于PHP 7的兼容性检查。
• adamculp/php-code-quality - 包含了多种代码质量检查的Docker镜像，其中包含了PHPCompatibility。
• grumphp-php-compatibility - GrumPHP插件，可以方便地在本地或CI环境中集成PHPCompatibility。
• Moodle codechecker - Moodle的代码样式检查插件，内置了PHPCompatibility的支持。

这些项目丰富了整个PHP开发者生态系统，提供了更广泛的兼容性和代码质量保证手段。