Title: PHPCS scans for PHP version compatibility Author: WordPress VIP Documentation Published: September 19, 2023 Last modified: December 22, 2023 --- 1. [WordPress on VIP](https://docs.wpvip.com/wordpress-on-vip/) 2. [PHP](https://docs.wpvip.com/wordpress-on-vip/php/) 3. [Version updates for PHP](https://docs.wpvip.com/wordpress-on-vip/php/versions/) 4. PHPCS scans for PHP version compatibility # PHPCS scans for PHP version compatibility Before a PHP version is updated on a [WordPress VIP Platform environment](https://docs.wpvip.com/vip-platform/environments/), all PHP files in an application’s GitHub repository should be scanned with PHPCS for potential incompatibility issues, and the identified issues should be resolved. PHPCS scanning an application’s code on a local machine increases the likelihood of a smooth update to a new PHP version on a VIP Platform environment.  **Prerequisites** On the user’s local machine: * [The application’s `wpcomvip` GitHub repository](https://docs.wpvip.com/wpcomvip-github-repository/) is [`git` cloned](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository). * [PHPCS is installed](https://docs.wpvip.com/php_codesniffer/). * The updated version of PHP is installed: - **[macOS](https://formulae.brew.sh/formula/php) ** - **[Windows](https://windows.php.net/download) ** - **Linux using `apt`: ** Identify the PHP package on the [Debian wiki page](https://wiki.debian.org/PHP) for the updated version. Use the `apt install phpX.Y` command to install the package, where `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`:** The `yum install php-X.Y` command can be used to install PHP on `yum` based systems, where `X.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. ## Considerations Performing scans with PHPCS **will not detect every possible PHP version compatibility issue**, but they will help identify the most common issues. * All issues detected by PHPCS 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 update.  ## Run a PHPCS scan for PHP version compatibility [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) (PHPCS) tokenizes PHP files and detects violations of a defined set of coding standards. Customers are strongly encouraged to use the [WordPress Coding Standards](https://github.com/WordPress/WordPress-Coding-Standards) and the [VIP Coding Standards](https://github.com/Automattic/VIP-Coding-Standards) when using PHPCS to scan their wpcomvip GitHub repository application code. **Note** PHPCS commands on a local machine running [Windows may require different formatting](https://www.php.net/manual/en/install.windows.commandline.php) than the command examples shown below. 1. Add the `[PHPCompatibilityWP](https://github.com/PHPCompatibility/PHPCompatibilityWP)` standard.** **The `PHPCompatibilityWP` standard analyzes a codebase for PHP cross- version compatibility. Install the `PHPCompatibilityWP` standard globally on a local machine with this command: ```wp-block-preformatted composer g require --dev phpcompatibility/phpcompatibility-wp:"*" ``` 2. Check out each branch locally using `[git checkout](https://git-scm.com/docs/git-checkout)`, then scan the checked-out branch’s code with the formatted PHPCS command. All repository branches that deploy code to a VIP Platform environment should be PHPCS scanned for PHP version compatibility. ```wp-block-preformatted phpcs --standard=PHPCompatibilityWP --severity=1 --runtime-set testVersion - --extensions=php ``` 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 the `example- site` repository has been cloned to `Desktop/working-folder/example-site`, the repository’s path value in the command will be `working-folder/example-site`. * **[Version of PHP to scan against](https://github.com/PHPCompatibility/PHPCompatibility#sniffing-your-code-for-compatibility-with-specific-php-versions):** 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 to `8.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: ```wp-block-preformatted phpcs --standard=PHPCompatibilityWP --severity=1 --runtime-set testVersion 8.1- --extensions=php example-site ``` 3. Make updates to the application code based on the [feedback on existing warnings and errors](https://docs.wpvip.com/vip-code-analysis-bot/phpcs-report/) identified within the code. ## Upcoming releases of `PHPCompatibility` `PHPCompatibility` is a dependency of `PHPCompatibilityWP`. The [upcoming release version 10.0.0](https://github.com/PHPCompatibility/PHPCompatibility/issues/1236#issuecomment-708443602) 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 the `PHPCompatibilityWP` 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: ```wp-block-preformatted $ 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: December 22, 2023