Acquia Cloud Platform: Upgrading a Drupal 9 site from PHP 7.4 to PHP 8.0 using Acquia Lando

PHP 7.4 is coming to an end of life! So I need to upgrade to PHP 8.0 ASAP!

From Acquia’s PHP 7.4 Retirement Announcement:

Acquia is ending support for PHP 7.4 in favor of PHP 8.0 on Monday, 3 October 2022. At that time, we will remove PHP 7.4 and convert all remaining environments to PHP 8.0 except for those customers who have purchased long-term support for PHP 7.4. This deadline will not be extended, as it is critical your application be upgraded to ensure its continued security.
Go to the PHP 7.4 Retirement Announcement: https://support-acquia.force.com/s/article/PHP-7-4-Retirement-Announcement

Let’s get started!

I use Acquia lando for local development. Go to this post if you’d like to learn how to get started with Acquia Lando:

Open your Terminal, go to your codebase folder and Start lando:

cd drupal9/
lando start

The Recommended version for Drupal 8 is: 8.9.20

For Drupal 9 sites, all versions should work fine, but the latest version is recommended.

Execute the following lando/drush command and make sure your Drupal 8 or 9 application meets the minimum requirements:

lando drush status

Make sure you don’t have any uncommitted changes and pull any changes from origin to your local machine:

git status
git pull

Create a new branch, I called mine “php8.0-upgrade”:

git branch php8.0-upgrade

Switch to the new branch:

git checkout php8.0-upgrade

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

For this, I will use the PHPCompatibility library that can be installed locally via composer.

https://github.com/PHPCompatibility/PHPCompatibility/#installation-in-a-composer-project-method-1

Add the following lines to the require-dev section of your composer.json file.

"require-dev": {
    "phpcompatibility/php-compatibility": "*"
},
"prefer-stable" : true

PHP CodeSniffer has to be informed of the location of the standard.

If PHPCompatibility is the only external PHP CodeSniffer standard you use, add the following to your composer.json file to automatically run the necessary command:

"scripts": {
    "post-install-cmd": "\"vendor/bin/phpcs\" --config-set installed_paths vendor/phpcompatibility/php-compatibility",
    "post-update-cmd": "\"vendor/bin/phpcs\" --config-set installed_paths vendor/phpcompatibility/php-compatibility"
}

Save the changes and exit composer.json.

Execute “composer update” to install the PHPCompatibility library and to upgrade packages to their latest versions:

composer update

It looks like I need to upgrade my version of BLT. I just edited my composer.json file and replaced the version of “acquia/blt” from “^12.0” to “^13.0”:

https://github.com/acquia/blt/releases

Save the changes and exit composer.json.

Execute “composer update” to upgrade BLT:

composer update

Now my BLT was upgraded to 13.5.2:

I will scan my local environment to help detect possible errors prior to switching the PHP version.

Command usage:

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

Because I’m using Acquia Lando, I need to execute the following lando command to SSH into my local application in order to execute the phpcs command:

lando ssh

I’m sitting at the root of my application so I will replace “/path/to/codebase” with “.”:

phpcs -p . --standard=PHPCompatibility --runtime-set testVersion 8.0

If you don’t want warnings included in the output, specify the -n command line argument:

phpcs -n . --standard=PHPCompatibility --runtime-set testVersion 8.0

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

The key things to focus on issues flagged by the tool are:

  • Libraries, packages, etc included by composer.
  • Drupal core and modules.
  • Drush Version.
  • And specially Custom Code! (modules and themes).

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.

My Drupal 9 application is super simple, I don’t have any custom code or themes installed at the moment.

I will go ahead and update my Acquia Lando environment to PHP 8.0. First, stop lando!:

lando poweroff

Edit the .lando.yml file and change the version of PHP from 7.4 to 8.0. I’ve also changed the value of acli_version from ‘1.30.1’ to latest:

Save the changes and exit the file.

Let’s rebuild lando:

lando rebuild

Now Lando is running with PHP 8.0.

Edit your composer.json file and change the version of PHP. In the require section, change “php”: “>=7.4” with “php”: “^8.0”, and in the platform section, change “php”: “7.4” with “php”: “8.0”:

Save the changes and exit the file.

Now we can update all the modules and libraries with composer:

composer update

Always check for database updates and configuration changes:

Push your changes to the repo:

git status
git add -A
git commit -m "Updated Lando and my Drupal 9 site to PHP 8.0."

Merge the branch into Master:

git checkout master
git merge php8.0-upgrade

Now push the merged changes on master to origin:

git push

Create a Tag, tags are very much like a branch that doesn’t change, it’s just a pointer to a specific commit.

Git tag structure: git tag -a v1.6 -m “Annotated message for my version 1.6”

git tag -a leo-1.1.0 -m "Updated Lando and my Drupal 9 site to PHP 8.0."

Synchronize release tags:

git push --tags

Push the new codebase to Cloud Platform, I will push the new codebase, database, and files to my dev environment:

lando push

Push code to? <Select the desired target environment (Dev or Test)>

Push database to?  <Select the desired target environment (Dev, Test, or None)>

Push files to? <Select the desired target environment (Dev or Test)>

Login to your Acquia Cloud Platform account and go to the Environments page and click the switch code button of your dev environment:

Select your new tag and click the continue button:

You will get a confirmation prompt. Click the “Switch” button:

After the process is done, you should see your tag in the dev environment:

Next, within the Acquia Cloud UI, select the dev environment and click the “Configuration” tab located in the bottom left corner.

Select “PHP 8.0” and click the “Save” button.

Now, it’s time to test your dev site and make sure everything is working fine.

Check the Status report and make sure everything looks fine in there:

After you make sure everything is in order, you should be able to move you dev site to the test environment, and then to production. Don’t forget to change the PHP version of your test and prod environments to PHP 8.0.

Congratulations!! You have updated your site, your codebase, and your Acquia Cloud platform environments to PHP 8.0 successfully!

Useful Resources