Quick Intro: PhpCompatibility for PHPCS

Sooner or later, there will come a time when you will need to migrate your projects to different PHP versions. How will you check if you’re compatible with a PHP version different to the one you’ve been developing on?

One possibility is always to install the version of PHP we want to migrate to, run php -l or something like PHPSA to check for syntax errors, check the PHP documentation for known issues with the migration and hope for the best. Or, we can use some available third party tools to check for PHP version compatibility in our projects.

Check compatibility with PHPCompatibility

PHPCompatibility is a set of sniffs we can install on top of PHPCS. This tool allows us to check our project’s compatibility with both newer and older versions of PHP. If you are not familiar with PHP QA tools, PHPCS is a tool which inspects PHP, JavaScript, and CSS for different code violations based on different sets of coding standards.

The current iteration of PHPCompatibility supports PHP versions up to PHP 7.

Installing PHPCompatibility

PHPCompatibility can be installed via Pear or via Composer. For this particular case, we will install PHPCS using Composer and then deploy our PHPCompatibility coding standards directly on top of it.

For a local installation:

composer require "squizlabs/php_codesniffer=2.*"

After PHPCS is installed, let’s move into the PHPCS /Standards folder that’s located in /vendor/squizlabs/php_codesniffer/CodeSniffer/Standards and run:

git clone https://github.com/wimg/PHPCompatibility.git

This command will deploy the PHPCompatibility coding standard directly into our standards folder, together with the coding standards already bundled in PHPCS. To check if both PHPCS and PHPCompatibility were successfully installed just run the command:

./vendor/bin/phpcs -i

This will list all the installed standards. We should see PHPCompatibility among them.

For a global installation, the same method is valid, just be sure to use Composer’s global require:

composer global require "squizlabs/php_codesniffer=2.*" 

and then clone PHPCompatibility into the following folder:

~/.composer/vendor/squizlabs/php_codesniffer/CodeSniffer/Standards

Using PHPCS

If you never used PHPCS before, it is always good to start with ./vendor/bin/phpcs -h. This will show us the PHPCS help section.

Before we delve into the use of the PHPCompatibility standard, there are some PHPCS commands that will help us make our compatibility tests faster, more efficient and in line with the results we need:

• -i – do not print warnings. This option will be helpful if we have a long list of messages and want to filter out the warnings to focus on the errors.

• -l – will only check the local directory, without recursion.

• -p – show progress of the run. Especially useful for big projects, to maintain status.

• -i – show the list of installed coding standards.

• <file> – the file or folder to check.

• <extensions> – a comma separated list of file extensions to check.

• <generator> – uses either the HTML, Markdown or Text generator. It forces documentation generation instead of just doing the check.

• <patterns> – a comma separated list of patterns to ignore files and folders (e.g. vendor).

• <severity> – the minimum severity of a problem required to display an error or warning.

• <standard> – the name or path of the coding standard to use.

• <runtime-set> – some individual standards also require particular configuration options, which is also the case with PHPCompatibility. This command’s syntax is as follows:

  phpcs --runtime-set <option> <value>`
  

This list is far from exhaustive, but should be of great use in fine tuning our checks.

Checking compatibility

To check compatibility we can run the following command:

./vendor/bin/phpcs --standard=PHPCompatibility --runtime-set testVersion 7 <path>

With this command, we are using the PHPCompatibility standard with the runtime-set option we saw earlier. We are checking for compatibility with PHP 7 on the file or folder defined by <path>.

The tool will output something similar to this:

Note that if you are testing backwards compatibility, it is advisable that you execute PHPCS on the latest PHP version available. For example, if you have the keyword yield in your code, PHPCS can only recognize it if you’re running PHP 5.5 or higher on your machine. It will only tell you it is not available in previous PHP versions if it actually knows what it is.

If we want to test for .php files only, we can use the <extensions> option. Adding it to the command we used earlier:

./vendor/bin/phpcs --standard=PHPCompatibility --extensions=php --runtime-set testVersion 7 <path>

For a detailed report we can use the option --report-full=<path>.txt.

To ignore files or folders in the compatibility test (for example, the aforementioned vendor folder, and a folder with tests) we can use the option --ignore=*/tests/*,*/vendor/* <path>. This way, the designated files and folders will not be tested for compatibility.

All the PHPCS options we saw earlier can be used to help make a better use of the tool.

A real life example

Of course, we also want to know if this tool can help us with a real life, production type application. Let’s use it on a complex application to see the results. I’ve chosen PHPMailer for this one.

git clone https://github.com/PHPMailer/PHPMailer.git mailer
cd mailer
composer install

This will clone PHPMailer into the /mailer folder and install all its dependencies. After that, we need to install both PHPCS and the PHPCompatibility standard:

composer require "squizlabs/php_codesniffer"
cd vendor/squizlabs/php_codesniffer/CodeSniffer/Standards
git clone https://github.com/wimg/PHPCompatibility.git

Finally, lets run the PHPCompatibility standard on a single file (we can now also run it on the whole project, but let’s use a single file for this demonstration).

./vendor/bin/phpcs --standard=PHPCompatibility --extensions=php --runtime-set testVersion 5.6 class.phpmailer.php

As we can see, even though PHPMailer is not quite PHP 5.6 ready, we have all the information needed to upgrade the code.

Hope this quick tip tool introduction helped! How do you test for compatibility?

Frequently Asked Questions (FAQs) about PHPCompatibility Standard for PHPCS