Hey there, and welcome to Learn WordPress.
In this tutorial, you're going to learn about testing your WordPress products for PHP version compatibility.
You will learn why it's important to test for PHP version compatibility,
where to find information about PHP version changes,
as well as two methods to test your plugins and themes against newer PHP versions.
WordPress is written in PHP, and as such, it needs to be able to run on at least the minimum supported version of PHP that is available to web hosts.
While WordPress recommends a specific minimum version of PHP,
all the PHP versions will eventually reach end of life, and will not receive any security updates in the near future.
For example, the current minimum recommended PHP version to run WordPress is 7.4,
which reached end of life status on the 28th of November 2022.
WordPress Core itself is considered compatible with select explicit exceptions,
with PHP 8.0, 8.1, and beta compatible with PHP 8.2 and 8.3.
However, they cannot guarantee that all plugins and themes will be compatible with current or future versions of PHP.
As a plugin or theme developer, it's therefore important to have a process in place to test your products for PHP version compatibility.
In order to know when and how PHP versions are going to change,
it's a good idea to refer to the official PHP website at www.php.net.
On the supported versions page, you can find information about which versions are currently supported,
at what level of support, and which versions are end of life.
At the time of this recording, all PHP 7 versions are end of life.
PHP 8.0 is supported for security fixes only,
and PHP 8.1, 8.2, and 8.3 are actively supported,
meaning bug and security flaws will be fixed.
Note that PHP 8.0 will only be supported for security fixes till November 2023,
which is around the time PHP 8.3 will be released, and then PHP 8.0 will be considered end of life.
In the 'Appendency' section of the PHP documentation,
you can find the guides on migrating from older PHP versions,
which lists the most important changes between the older version and the newer.
For example, the 'Migrating from PHP 7.4 to PHP 8.0' guide lists the most important changes between 7.4 and 8.0.
For the purposes of this tutorial, let's look at an example plugin.
Plugin registers a shortcode, which fetches a list of posts, and displays the post title of each post whenever the shortcode is used.
The 'PostFetcher' class handles the fetching of the posts.
Tasting the shortcode on a page, you can see that it works as expected when running PHP 7.4.
There are a few ways to test for PHP version compatibility,
which require different combinations of newer PHP versions and installation of various tools.
For the purposes of this tutorial, you will look at two possible methods, each with their own pros and cons.
The manual method involves setting up a WordPress environment with a PHP version that you want to test for,
and then testing your plugin in that environment.
Setting up this environment can be done in a few ways,
but the most common option would be to use a local development environment that supports changing PHP versions,
such as MAM, Larragon, LocalWP, and DevKinsta.
For the purposes of this example, we'll test on PHP 8.1.
A quick way to check that you're on the right version is if you create an info.php file in the root of your WordPress install and use the following code.
Then, navigate to that info.php file in your browser, and you should see the PHP version displayed.
Once you have your test environment set up, you need to enable WordPress debugging.
To do this, edit the wp-config.php file and update the line which defines the wp-debug constant, setting it to true.
Additionally, add the wp-debug display and set it to false, and add the wp-debug-log constant and set it to true.
This will ensure that all errors are logged to the debug log file in the wp-content directory.
You can also set your wp-debug-log constant to a custom location by specifying the path to the file, for example,
then test your plugin by refreshing the page.
Notice that the shortcode functionality breaks and the list of posts don't appear.
Now take a look at the debug log.
If you look at the debug log, you'll see something like the following error displayed.
This tells us that there's an error on line 36 of the plugin.
If you go to line 36 of the plugin, you'll see the following code,
and you'll see that it's trying to loop through the this_posts property, which is null for some reason.
The reason might not be immediately obvious, so you might have to dig into the migrating guide to see what's going on.
Under the other incompatible changes section, you see the following change.
Methods with the same name as the class are no longer interpreted as constructors.
The _construct method should be used instead.
So in this case, the class constructor method needs to be updated.
So if we change this to construct.
Once that's fixed, refresh the page.
And you should see that the plugin is working again as expected.
While manual testing does work, it's a tedious process.
Fortunately, you can also automate most tests using a tool called PHP Unit.
This will allow you to continuously safeguard your code both against bugs and for PHP compatibility issues.
But using PHP Unit is outside of the scope of this tutorial.
There are also tools that you can use to test for PHP compatibility.
The most useful being the aptly named PHP compatibility tool,
which is a set of rules for the PHP Code Sniffer tool.
PHP Code Sniffer is a command line application that can be used to scan your code for errors and warnings.
PHP compatibility is a set of rules that can be used with PHP Code Sniffer to scan your code for PHP version compatibility.
For WordPress developers, there is a specific rule set called PHP compatibility WP,
which is a PHP compatibility rule set for WordPress projects.
What's great about PHP compatibility and PHP compatibility WP is that you don't have to configure a different PHP version to use it.
You can use it with your existing PHP version and it will check your code against the rules for the PHP version that you specify.
To install and use PHP compatibility WP, you need to install Composer, which is a dependency manager for PHP projects.
For Composer to work, you also need PHP installed on your computer so that you can use the PHP CLI binary,
which allows you to run PHP scripts in the terminal instead of just the browser.
Installing Composer is outside of the scope of this tutorial,
but you can find instructions on the Composer website for both macOS and Linux and Windows.
You can find ways to install PHP on your system on the PHP website under the Installation and Configuration section.
Once you install PHP, make sure to add the path to the PHP CLI binary to the operating system path of your computer,
so that you can run PHP commands from anywhere on your computer.
You can check that you have PHP installed by running the following command in your terminal, PHP -v.
Similarly, you can check that you have Composer installed by running the following command in your terminal, Composer -Uppercasep.
Once you have Composer installed, you can initialize the Composer project by running the following command inside the plugin or theme directory.
If you're already using Composer for your plugin, you probably can skip this step.
The command is Composer -init.
This will initialize a new Composer project in your directory.
You can accept the defaults for most of the questions.
The command asks you to define your dependencies interactively and your dev dependencies interactively.
You should also know.
You can also skip the PS4 auto-logue mapping unless you're planning to use it.
Once this is done, you will have a Composer.json file, which is the file Composer uses to manage your project dependencies.
Next, you will need to install the Composer plugin to manage the installed path setting for PHP Code Sniffer by running the following from the command line.
If you already have this plugin installed, you can ignore this.
Then you can install the Composer installer plugin and the PHP compatibility tool by running the following commands.
Composer require dev / dealer direct / PHP Code Sniffer Composer installer
and Composer require dev / PHP compatibility / PHP compatibility / WP.
This will both set up and install the required dependencies in your Composer JSON 4.
Currently, the stable release of PHP compatibility is 9.3.5.
However, the most recent Sniffs are part of an upcoming version 10.0.
The current stable version of PHP compatibility WP is 2.1.4.
When version 10 of PHP compatibility is released, version 3 of PHP compatibility WP will be released, which will depend on PHP compatibility version 10.
In the meantime, it is possible to install the dev / developer branch of PHP compatibility to run PHP CS with the cutting edge additions of PHP 8.0 Sniffs before their release in version 10 of PHP compatibility, as detailed in this WordPress VIP documentation.
To do this, run the following commands to alias the dev / developer branch of PHP compatibility.
These commands will alias the dev / developer branch of PHP compatibility to a 9.x version, which is within the allowed range for PHP compatibility, and set PHP compatibility WP to install the later stable 2.1 version.
Once PHP compatibility 10 and PHP compatibility WP 3 are released, it should be possible to update the PHP compatibility WP version constraint to 3.0, which will depend on version 10 of PHP compatibility.
With all this installed, you can now run the PHP compatibility WP tool on your plugin file.
The recommended way to do this is to run PHP compatibility WP against a specific base version of PHP.
In this example, you can run it against the version 7.4 of PHP and above by setting the test version runtime to 7.4.
When you run it, you see this output.
Notice how this is the same error as reported in the manual method, but this time it's a lot more specific.
It tells exactly what line the error is on, and what the error is.
So now we can fix the class constructor again.
One of the considerations when using something like PHP compatibility WP is that it can't pick up every single compatibility error.
For example, one of the other changes from PHP 7.4 to PHP 8 is the removal of the ability to use array key exists with objects, and instead to use something like property exists.
However, the PHP compatibility WP tool doesn't know if the variable you're passing to array key exists is an array or an object, so it can't warn you about this.
This is where automating your manual tests would come in handy.
When you run the tests in a new PHP environment, the test would fail, alerting you to a possible problem.
And with logging enabled, you'll see the error log to the log file.
Ultimately, combining tools like PHP compatibility with automated testing and the manual testing process we've discussed will allow you to ensure that your plugin is compatible with current and future versions of PHP.
Happy coding!