Dries Buytaert

Drupal upgrades: tools and workflow

This page is part of my digital garden. It is more like a notebook entry than a polished blog post. It's a space where I document learnings primarily for my own reference, yet share them in case they benefit others. Unlike my blog posts, these pages are works-in-progress and updated over time. Like tending to a real garden, I periodically refine its content. I welcome suggestions for improvements at dries@buytaert.net.

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 Drupal 11 upgrade status report in the administration interface.
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:

    $ ddev composer require –dev drupal/upgrade_status

    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:

    $ ddev drush pm-enable upgrade_status

    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:

$ ddev config –-php-version 8.3

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

$ ddev debug migrate-database mariadb:10.11

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.

Terminal output showing successful run of Drupal Check with no errors.
Output of Drupal Check command indicating no deprecated code was found.

  1. Installation:

    $ ddev composer require –dev mglaman/drupal-check

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

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

    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:

$ php vendor/bin/phpstan analyze -l 2 docroot/modules/custom