Ensuring project’s compatibility with new PHP versions

Before continuing, this article assumes you are familiar with the basics of Composer.

PHP releases a new version every 2 years, and in the 3rd year of its lifecycle, only critical security issues are addressed. After its 3rd year, it is no longer supported.

Every new release may contain some or all of the following:

Backward incompatible changes
New functions
Deprecated features
New features
Removed extensions, etc.

For this reason, it is very important to ensure that our WordPress plugins and themes are compatible with future PHP versions.

You may have seen the plugin header for WooCommerce, it is something like this:

<?php
/**
 * Plugin Name: WooCommerce
 * Plugin URI: https://woocommerce.com/
 * Description: An eCommerce toolkit that helps you sell anything. Beautifully.
 * Version: 6.4.0-dev
 * Author: Automattic
 * Author URI: https://woocommerce.com
 * Text Domain: woocommerce
 * Domain Path: /i18n/languages/
 * Requires at least: 5.7
 * Requires PHP: 7.2
 *
 * @package WooCommerce
 */
Code language: PHP (php)

Focus on the highlighted line. It says “Requires PHP: 7.2”

What it translates to: WooCommerce version 6.4.0-dev will only work on environments which run on PHP 7.2 and above.

Similarly, our plugins must hold true to whatever is claimed in their headers.

Our plugin’s compatibility

Let’s say we built a WordPress plugin years ago on PHP 5.6 and we want to ensure the PHP features used by our plugin are compatible with all PHP versions released after 5.6.

For the sake of learning, let’s use an example that works on PHP 5.6 but fails on 7.4.

Let’s assume our plugin uses the function hebrevc(). (It’s not necessary to know what it does.)

This function:

worked until PHP 7.3
was deprecated in 7.4
and completely removed in 8.0

If our plugin header says it requires a minimum PHP version 5.6, that is true in all sense. But it also implies that it works on 5.6 and above. However, our plugin will fail on PHP versions 7.4 and above.

On 7.4, the following deprecation message will be shown:

Deprecated: Function hebrevc() is deprecatedCode language: Access log (accesslog)

On 8.0, the following fatal error will be caused:

Fatal error: Uncaught Error: Call to undefined function hebrevc() Code language: Access log (accesslog)

To ensure stability of our plugin across multiple versions of PHP, we can use a tool called PHP CodeSniffer which detects violations in your code depending on the standard you choose. By default PHPCS (as it is shortly called) provides a handful of built-in standards, but these are of no use to us. We will instead use a 3rd party standard called PHPCompatibility.

Setting up PHPCS and PHPCompatibility

Now I know I said we will be installing a bunch of things. That would be a multi-step process. We can instead do all of that with a single command by using 10up’s 10up/php-composer composer package. Open up your terminal and run the following in your plugin/theme root:

composer require --dev 10up/phpcs-composer:dev-masterCode language: Bash (bash)

This single command will setup PHPCS, WPCS and PHPCompatibility. WPCS is another standard to detect WordPress related coding violations. It is included in the 10up/php-composer package, however we won’t be using it.

To test your plugin against PHP versions 5.6 and above, run the following:

./vendor/bin/phpcs . --standard=PHPCompatibilityWP --extensions=php --runtime-set testVersion 5.6- Code language: Bash (bash)

What exactly is happening?

./vendor/bin/phpcs . will run PHPCS on all the files in the current directory recursively.
--standard=PHPCompatibilityWP will set the standard to PHPCompatibilityWP. At this point you might be wondering what is the difference between PHPCompatibility and PHPCompatibilityWP? The latter standard contains additional rules specific to WordPress. You can read more on it here.
--extensions=php PHPCS will sniff PHP, JavaScript and CSS by default. Since we are only concerned with PHP files, we explicitly tell PHPCS to run the sniff only on the PHP files.
--runtime-set testVersion 5.6- The --runtime-set flag is used to set configurable options in PHPCS and it accepts 2 arguments, somewhat similar to a key-value pair. In our case, the key and value pairs are testVersion and 5.6-

The hyphen suffix in 5.6- indicates that we want to test our plugin for PHP 5.6 and above.

When we run our command, we get the following output:

FILE: /Users/machine/public/wp-content/plugins/some-plugin/index.php
--------------------------------------------------------------------
FOUND 0 ERRORS AND 1 WARNING AFFECTING 1 LINE
--------------------------------------------------------------------
 17 | WARNING | Function hebrevc() is deprecated since PHP 7.4
--------------------------------------------------------------------

Time: 174ms; Memory: 4MBCode language: Bash (bash)

To test for a single PHP version, remove the hyphen. If we wish to test a range of versions, for example from 5.6 to 7.4, set it as --runtime-set testVersion 5.6-7.4

Things to keep in mind

PHPCS will not run the plugin itself. All it does is scan the plugin files one by one. While our plugin has a min. requirement of PHP5.6, PHPCS itself can run on PHP>=5.4.

Once the setup is completed, it is best to implement this on some CI pipeline like GitHub Actions or CircleCI where it runs at the pre-deployment stage, or maybe when a Pull Request is raised.

Thank you for reading!