Prepare application code for a PHP version upgrade
Before a PHP version is upgraded on a WordPress VIP Platform environment, all PHP files in an application’s GitHub repository should be scanned for potential incompatibility issues, and the identified issues should be resolved. PHP linting and PHPCS scanning an application’s code on a local machine increases the likelihood of a smooth upgrade to a new PHP version on the VIP environment.
The scanning steps outlined in this article will not detect every possible PHP version compatibility issue, but they will help identify the most common issues. As a next step, thorough testing of an application’s code is strongly recommended on a non-production VIP Platform environment with the upgraded version of PHP.
- All issues detected by PHPCS and PHP linting should be investigated and resolved as required. It is possible for some of the reported issues to be false positives that do not need resolution.
- In some cases, compatibility code may be required to ensure that an application’s code works with both the current version of PHP and the PHP version that will be running after the upgrade.
Prerequisites
On the user’s local machine:
- The application’s
wpcomvip
GitHub repository isgit
cloned. - PHPCS is installed.
- The upgraded version of PHP is installed:
- macOS
- Windows
- Linux using
apt
:
Identify the PHP package on the Debian wiki page for the upgraded version. Use the
command to install the package, whereapt install phpX.Y
X.Y
represents the version number. Upgrading the system or installing a third-party package may be required if Debian distribution does not yet support the PHP version that is needed. - Linux using
yum
:
Theyum install php-X.Y
command can be used to install PHP onyum
based systems, whereX.Y
represents the PHP version number. Upgrading the system or installing a third-party package may be required if the distribution does not yet support the PHP version that is needed.
PHP linting
PHP linting identifies code syntax problems present in a repository’s PHP files.
find <path-to-repository> -name '*.php' -type f -exec <path-to-local-php-version> -l '{}' \;
The PHP linting command requires the following values to be passed:
- Path to the cloned repository: The value of the path to the cloned repository is relative to the directory from which the PHP linting command is run. If the user is in the directory
Desktop
in the terminal prompt, and theexample-site
repository has been cloned toDesktop/working-folder/example-site
, the repository’s path value in the command will beworking-folder/example-site
. - Path to the installed version of PHP: This path value will differ across machines and should be identified by the user using
which php
(Mac OSX / Linux) orwhere php
(Windows). The path value'/usr/local/bin/php'
is used in the command example.
This example command is formatted to PHP lint a cloned repository named example-site
:
findexample-site
-name '*.php' -type f -exec '/usr/local/bin/php' -l '{}' \;
All repository branches that deploy code to a VIP Platform environment should be PHP linted for PHP version compatibility. Check each branch locally using git checkout
, then lint the checked-out branch’s code with the PHP command.
PHPCS scanning
PHPCS is a tool that scans a repository’s PHP files using a variety of standards to analyze code for security and performance.
Note
PHPCS commands on a local machine running Windows may require different formatting than the command examples shown below.
Add the PHPCompatibilityWP
standard
The PHPCompatibilityWP
standard analyzes a codebase for PHP cross-version compatibility.
This command will install the PHPCompatibilityWP
standard globally on a local machine:
composer g require --dev phpcompatibility/phpcompatibility-wp:"*"
Run a PHPCS scan for PHP version compatibility
phpcs --standard=PHPCompatibilityWP --severity=1 --runtime-set testVersion <php-version>- --extensions=php <path-to-repository>
The PHPCS command requires the following values to be passed:
- Path to the directory or file to be scanned: The path value can be an absolute path or a relative path to the directory from which the PHPCS command is run. If the user is in the directory
Desktop
in the terminal prompt, and theexample-site
repository has been cloned toDesktop/working-folder/example-site
, the repository’s path value in the command will beworking-folder/example-site
. - Version of PHP to scan against: Specify the version(s) of PHP that the code should be scanned against with the
--runtime-set
parameter. For example, to scan against PHP versions 8.1 and above, set--runtime-set testVersion
to 8.1 with a hyphen :8.1-
. To scan against PHP version 8.1 only, set the value to8.1
without the hyphen. The set value can be any PHP version supported by PHPCompatibilityWP. Refer to documentation for PHPCompatibilityWP on support for the version you are using.
This example command is formatted to scan a cloned repository named example-site
for compatibility with PHP version 8.1 and above:
phpcs --standard=PHPCompatibilityWP --severity=1 --runtime-set testVersion 8.1- --extensions=php example-site
All repository branches that deploy code to a VIP Platform environment should be PHPCS scanned for PHP version compatibility. Check each branch locally using git checkout
, then scan the checked-out branch’s code with the formatted PHPCS command.
Upcoming releases of PHPCompatibility
PHPCompatibility
is a dependency of PHPCompatibilityWP
. The upcoming release version 10.0.0 of the PHPCompatibility
standard will include:
- Improved compatibility with PHP 8.0+: Currently, PHP 7.4 interpreter should be used rather than PHP 8.0+ when scanning with PHPCS using the
PHPCompatibilityWP
standard. The dependencies of thePHPCompatibilityWP
standard have some remaining incompatibilities with the PHP 8.0 interpreter. - Improved detection of PHP 8.0+ incompatibilities: Currently, some PHP 8 incompatibilities are not yet detected by the
PHPCompatibilityWP
standard and its dependencies.
It is possible to install the dev-develop
branch of PHPCompatibility
to run PHPCS with the cutting-edge additions of PHP 8 sniffs before their release in version 10.0.0 of PHPCompatibility
.
To opt into the dev-develop
branch, run the following commands on the local machine:
$ composer config minimum-stability dev $ composer g require --dev phpcompatibility/phpcompatibility-wp $ composer g require --dev phpcompatibility/php-compatibility:"dev-develop as 9.99.99"
In the listed commands above, dev-develop as 9.99.99
aliases the develop
branch of PHPCompatibility
to a 9.x
version which is within the allowed range for PHPCompatibility
.
Last updated: May 25, 2023