WordPress Theme Minimum PHP Support Check
WordPress has recently bumped the minimum recommended PHP version from 5.2 up to 5.6, solidified by this commit accepting failures for older php version in the automated test suite. Themes for the wordpress.org directory are required to work (or gracefully fail) on the same versions of PHP that WordPress Core supports. That means that theme developers need to account for sites that could be running any PHP versions between 5.6 and 7+. Themes can choose to support any PHP version they want but they must still prevent fatal errors and other problems if they are run on any PHP version which WordPress itself supports.
In the past it was common for a theme to choose to support PHP versions 5.6 and above (because 5.2 hit EOL so very long ago, right?). It’s becoming somewhat popular now for them to chose to support PHP 7+ only.
Preventing Fatal Errors on Unsupported PHP Versions
Core has added some fatal error prevention checks that run on activation of a plugin or theme. This checking can catch some fatal errors but not all of them.
Core also recently added a minimum PHP version check for plugins that lets them define their support inside of the readme. This unfortunately is not (yet) available for themes. Themes should add their own minimum PHP version checks to the theme.
Checking PHP Version on Theme Activation and Reverting When Not Supported
You can make sure that your theme does not cause a fatal error on unsupported PHP versions by performing a PHP version compare check at theme activation and reverting to the previous theme if the version check fails and the site is running an unsupported version.
For this to work the first thing need to make sure of is that your theme contains no issues with PHP compatibility between PHP 5.6 and upwards in any of the code which executes immediately when a file is parsed. This basically means that none of the code found at root level of a file or code that is run on a hook that fires before we do the version check.
You perform the version check by using the after_switch_theme hook, the phpversion() function (or the PHP_VERSION constant) and version_compare(). Here is some example code with comments that prevents theme activation on a server that’s PHP version is below 7.1. Just change the targeted version in the constant so it points at the version you want.
<?php
/**
* Set a constant that holds the theme's minimum supported PHP version.
*/
define( 'PATTONWEBZ_MIN_PHP_VERSION', '7.1' );
/**
* Immediately after theme switch is fired we we want to check php version and
* revert to previously active theme if version is below our minimum.
*/
add_action( 'after_switch_theme', 'pattonwebz_test_for_min_php' );
/**
* Switches back to the previous theme if the minimum PHP version is not met.
*/
function pattonwebz_test_for_min_php() {
// Compare versions.
if ( version_compare( PHP_VERSION, PATTONWEBZ_MIN_PHP_VERSION, '<' ) ) {
// Site doesn't meet themes min php requirements, add notice...
add_action( 'admin_notices', 'pattonwebz_min_php_not_met_notice' );
// ... and switch back to previous theme.
switch_theme( get_option( 'theme_switched' ) );
return false;
};
}
/**
* An error notice that can be displayed if the minimum PHP version is not met.
*/
function pattonwebz_min_php_not_met_notice() {
?>
<div class="notice notice-error is_dismissable">
<p>
<?php esc_html_e( 'You need to update your PHP version to run this theme.', 'pattonwebz' ); ?> <br />
<?php
printf(
/* translators: 1 is the current PHP version string, 2 is the minmum supported php version string of the theme */
esc_html__( 'Actual version is: %1$s, required version is: %2$s.', 'pattonwebz' ),
PHP_VERSION,
PATTONWEBZ_MIN_PHP_VERSION
); // phpcs: XSS ok.
?>
</p>
</div>
<?php
}
Originally I wrote that code for my own theme and then reworked it somewhat to use as an example for the Theme Review Team to show to authors that were needing a check for this in their own themes. Eventually I turned it into a reusable class which I can add easily through composer in any of my projects that need it.
The class uses namespaces (which are now totally fine by Core standards but not suitable for very, very old php versions) so bear that in mind if you plan to use it somewhere that may only have PHP 5.2.
The repo for the theme PHP compatibility checking class is on GitHub and on Packagist so you can easily install it with composer.
composer require pattonwebz/theme-php-version-support-check
The file should be autoloaded so simply instantiate the class early in your theme and let it do it’s thing.
