Preparing For Your PHP 8.1 Upgrade

  • Last updated
  • 1 minute read


The key goal is to provide the basic steps for compatibility scanning and deploying PHP 8.1 across your environments and applications.


This tutorial looks to provide a list of tools and processes that customer teams may use to efficiently update your existing applications on Acquia to PHP 8.1. 
It will also cover requirements specific to existing Drupal versions.

See PHP End of Life Resources if you would like to explore Long Term support options. 


  1. Initial Scans

    The first and best preliminary step is to start scans on local environments to help detect possible errors prior to switching the PHP version.

    The PHPCompatibility library can be installed locally via composer. See:

    This tool can be run to check compatibility without setting the environment to the target PHP version up front so, one may run checks while still using their current PHP version.

    Once installed the scan can be run via the following command:

    phpcs -p /path/to/codebase --standard=PHPCompatibility --runtime-set testVersion 8.1

    That command should target the project root and not just the docroot to ensure that all of your code is covered including possible dependencies from composer.

  2. Review and Update Code

    Once the report is generated from the tool, review the listed possible warnings and errors.

    The key things to focus on that may be flagged by the tool could be:

    • Libraries, etc. included by composer
    • Drupal core and modules
    • Custom code (modules and themes)
    • Drush Version. See Drush's docs on PHP compatibility.

    Pending which of the above that may have been flagged, take the time to update any contributed projects/modules to the latest compatible versions. 

    For custom code, make any adjustments as required and do ensure that no deprecated functions are continued to be used as that may hinder future updates.

  3. Update and Test Local Environments

    After the compatibility scans and remediations, the first best place to test will be in your local environment. Please review the below links for your local environment solution for how to update the PHP version there:

    For any environment solutions not listed here please refer to the documentation for your solution.

    Next, fully review your site and relevant error logs for any issues and ensure that there is no lost functionality in your application.


  4. Update and Test Cloud Environments

    Once a successful artifact has been created and is ready to deploy, it is time to begin updating cloud environments.

    First, choose which non-production environment that you wish to start with and deploy, the artifact that was created that contains all the compatibility changes.

    Next, within the Acquia Cloud UI, select the environment and choose the gearbox icon in the top right corner. Select the desired PHP version and scroll down and click “Save.”

    Once the task is completed, the environment is set and you may begin testing.

    Go through the site and test for any irregularities or errors and continue.

    For the rest of the environments, continue the same steps above until every environment is updated as needed

Other Recommendations

It is also recommended that you may develop a series of functional and regression tests with tools such as Behat, where you may be able to automatically and consistently test your application. This will also help to maintain consistency with future upgrades.

Follow Up

For any issues or other questions that may arise during these steps please do not hesitate to reach out to Acquia Support and your TAM!