Introduction
PHPCompatibility is a set of PHP_CodeSniffer rules that checks your code for cross-version compatibility. It can help you ensure your code runs smoothly across various versions of PHP, making it an invaluable tool for any PHP developer. This guide will walk you through how to install and use PHPCompatibility in your project.
Resulting output
After running PHPCompatibility on your PHP code, the output you receive is incredibly important. It gives detailed information about issues that might affect the compatibility of your code with different PHP versions.
Here’s a sample output:
FILE: /path/to/your/code/sample.php
----------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------
2 | ERROR | 'password_hash' is not present in PHP version 5.4 or earlier
----------------------------------------------------------------------
We’ll look at the exact meaning of this output further below.
Basic Usage
Step 1: Install PHP_CodeSniffer
The first step is to install PHP_CodeSniffer using Composer, a package manager for PHP. Run the following command:
composer require --dev squizlabs/php_codesniffer
Step 2: Install PHPCompatibility
After PHP_CodeSniffer is installed, the next step is to install PHPCompatibility. Use the following command:
composer require --dev phpcompatibility/php-compatibility
Step 3: Register PHPCompatibility with PHP_CodeSniffer
You’ll need to register PHPCompatibility with PHP_CodeSniffer to start using it. You can do this with the following command:
vendor/bin/phpcs --config-set installed_paths vendor/phpcompatibility/php-compatibility
Step 4: Running PHPCompatibility
You’re now ready to test your code for PHP compatibility. Run the following command:
vendor/bin/phpcs /path/to/your/code --standard=PHPCompatibility --extensions=php
Replace `/path/to/your/code` with the actual path to your PHP code. The `–extensions=php` option ensures that only PHP files are scanned.
Intermediate Usage
Step 1: Specify PHP Version
If you want to test your code against a specific PHP version, specify that version when you run PHPCompatibility :
vendor/bin/phpcs /path/to/your/code --standard=PHPCompatibility --runtime-set testVersion 7.4- --extensions=php
The `7.4-` means your code will be tested for compatibility with PHP 7.4 and all newer versions.
Step 2: Using Custom Ruleset
You can customize the rules PHPCompatibility checks against by creating a custom ruleset file. Create a file named `phpcs.xml` in your project root and add the following content:
<?xml version="1.0"?>
<ruleset name="Project">
<description>PHPCompatibility ruleset for my project.</description>
<config name="testVersion" value="7.4-"/>
<rule ref="PHPCompatibility"/>
</ruleset>
Now you can run PHPCompatibility with your custom ruleset:
vendor/bin/phpcs /path/to/your/code --standard=phpcs.xml --extensions=php
Advanced Usage
Step 1: Ignoring Specific Files or Folders
Exclude specific files or folders from being checked by adding `exclude-pattern` to your custom ruleset :
<exclude-pattern>/path/to/your/code/excluded-folder/*</exclude-pattern>
Step 2: Ignoring Specific Rules
Ignore specific compatibility checks by adding them to your `phpcs.xml`:
<rule ref="PHPCompatibility">
<exclude name="PHPCompatibility.FunctionUse.NewFunctions.array_columnFound"/>
This ignores the check for the usage of the `array_column` function introduced in PHP 5.5.
Step 3: Running PHPCompatibility in Continuous Integration (CI)
Integrating PHPCompatibility into your CI process ensures your code is always tested for compatibility with different PHP versions. Most CI tools allow you to run commands as part of the build process. Here’s how to add PHPCompatibility to a Travis CI configuration file:
before_script:
- composer require --dev squizlabs/php_codesniffer
- composer require --dev phpcompatibility/php-compatibility
- vendor/bin/phpcs --config-set installed_paths vendor/phpcompatibility/php-compatibility
script:
- vendor/bin/phpcs /path/to/your/code --standard=PHPCompatibility --extensions=php
By following these steps, you ensure your PHP code is consistently tested for compatibility with different PHP versions, helping to prevent bugs and improve the reliability of your code.
Analyzing PHPCompatibility Output
After running PHPCompatibility on your PHP code, the output you receive is incredibly important. It gives detailed information about issues that might affect the compatibility of your code with different PHP versions.
Here’s a sample output:
FILE: /path/to/your/code/sample.php
----------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------
2 | ERROR | 'password_hash' is not present in PHP version 5.4 or earlier
----------------------------------------------------------------------
In the above output:
- `FILE: /path/to/your/code/sample.php`: This is the file where PHPCompatibility found an issue.
- `FOUND 1 ERROR AFFECTING 1 LINE`: This shows the total number of issues found and how many lines of code are affected.
- `2 | ERROR | ‘password_hash’ is not present in PHP version 5.4 or earlier`: This is a detailed description of the issue. It consists of three parts:
- `2`: This is the line number where the issue was found.
- `ERROR`: This is the severity of the issue. PHPCompatibility categorizes issues as `ERROR` or `WARNING`. An `ERROR` is something that will cause your code to break in the PHP version you’re checking compatibility for, while a `WARNING` is something that might lead to unexpected behavior but won’t necessarily break your code.
- `’password_hash’ is not present in PHP version 5.4 or earlier`: This is the explanation of the issue. Here, the `password_hash` function is being used, which isn’t available in PHP version 5.4 or earlier. So, if your application needs to run on PHP 5.4, this line of code will cause an error.
You also receive a summary at the end of the report, giving you an overall picture of the compatibility check.
Understanding and addressing the issues highlighted in the PHPCompatibility output is crucial to ensure that your code can run on the intended PHP versions. When you’ve made changes to your code, you can run PHPCompatibility again to check if there are still compatibility issues.
