Dries Buytaert: Drupal upgrades: tools and workflow

When a new major version of Drupal is released, custom code often requires updates to align with API changes, including the removal of deprecated APIs.

Because I keep forgetting certain aspects of this workflow, I decided to document it for future reference.

Tools overview

Tool Interface Functionality Target Audience Upgrade Status module UI in Drupal Identifies deprecated code, hosting environment compatibility, and more Site administrators and developers Drupal Check Command-line Identifies deprecated code Developers, especially during coding and continuous integration (CI)

Upgrade Status module

The Upgrade Status module assesses a Drupal site's readiness for major version upgrades by checking for deprecated code and other compatibility issues.

Screenshot of a Drupal upgrade status report showing hosting environment compatibility checks.

1. Install the Upgrade Status module like you would install any other Drupal module:

   [code bash]$ ddev composer require –dev drupal/upgrade_status[/code]

   Here, ddev is the tool I prefer for managing my local development environment. composer is a dependency manager for PHP, commonly used to install Drupal modules. The –dev option specifies that the module should be installed as a development requirement, meaning it is necessary for development environments but not installed on production environments.

2. Enable the Upgrade Status module:

   [code bash]$ ddev drush pm-enable upgrade_status[/code]

   drush stands for "Drupal shell" and is a command-line utility for managing Drupal sites. The command pm:enable (where pm stands for "package manager") is used to enable a module in Drupal.

3. After enabling the module, you can access its features by navigating to the Admin > Reports > Upgrade status page at /admin/reports/upgrade-status.

Upgrading PHP and MySQL using DDEV

The Upgrade Status module might recommend updating PHP and MySQL, per Drupal's system requirements.

To update the PHP version of DDEV, use the following command:

[code bash]$ ddev config –-php-version 8.3[/code]

To upgrade the MySQL version of DDEV and migrate your database content, use the following command:

[code bash]$ ddev debug migrate-database mariadb:10.11[/code]

After updating these settings, I restart DDEV and run my PHPUnit tests. Although these tests are integrated into my CI/CD workflow, I also run them locally on my development machine using DDEV for immediate feedback.

Drupal Check

Drupal Check is a command-line tool that scans Drupal projects for deprecated code and compatibility issues.

I always run drupal-check before updating my Drupal site's code and third-party dependencies. This helps ensure there are no compatibility issues with the current codebase before upgrading. I also run drupal-check after the update to identify any new issues introduced by the updated code.

Output of Drupal Check command indicating no deprecated code was found.

1. Installation:

   [code bash]$ ddev composer require –dev mglaman/drupal-check[/code]

2. Run Drupal Check from the root of your Drupal installation:

   [code bash]$ ./vendor/bin/drupal-check –-memory-limit 500M docroot/modules/custom[/code]

   I usually have to increase the memory limit, hence the --memory-limit 500M.

Using PHPStan directly

In the future, I'd like to evaluate whether using PHPStan directly is simpler. This is a TODO for myself. Drupal Check is essentially a wrapper around PHPStan, offering default configuration such as automatically running at level 2. To achieve the same result with PHPStan, I should be able to simply run:

[code bash]$ php vendor/bin/phpstan analyze -l 2 docroot/modules/custom[/code]