Deprecation checking and correction tools to prepare for a new Drupal major version

Last updated on
14 December 2023

Use an IDE or code editor that understands deprecations

If you are developing Drupal code, it is best to use an IDE or code editor that understands deprecations (@deprecated annotations particularly). For example, IDEs like PHPStorm will cross out calls to deprecated methods and inform you of what should be used instead. Deprecated code use will be made visible as part of the development process.

Use drupal-check for deprecation testing

Matt Glaman built drupal-check (only for Drupal 8), which allows you to run a standalone PHP executable from the command line and get a report of any deprecated code used. This can be integrated in build processes and continuous integration systems. This helps ensure Drupal 9 compatibility of your custom code, contributed modules, and Drupal 7 to 8 migration code.

Use Upgrade Status for full site reporting

For a full site scan of all projects on a site, Upgrade Status provides a complete solution. It wraps the internals of drupal-check and runs scanning on custom and drupal.org contributed projects on your site. You can use this report to assess the overall major version compatibility of your site. Additional features on top of drupal-check include:

  • Per project scanning. Stored results and multi-result export.
  • Problem categorization based on deprecation version number.
  • Deprecate Twig syntax is detected.
  • Deprecated Drupal library use and extension of deprecated libraries is detected.
  • Missing core_version_requirement keys are noted for all scanned projects.

Upgrade Status also comes with Drush support if you prefer the command line.

Upgrade Status Drupal 8 module UI

Drupal.org testing support for deprecation checking

The drupal.org testing system also has support for deprecation checking. There are two methods:

  1. The execution of your module's test suite can be configured to fail when a deprecated code path (a trigger_error() with E_USER_DEPRECATED level) is reached. The effectiveness of this method depends on the extent of test coverage in your code.
  2. The same PHPStan deprecation testing tool can run on your project (similar to drupal-check and Upgrade Status' backend). This will produce a build artifact but will not (yet) fail the testing of your project.

You can use a testing issue with a drupalci.yml file or commit a custom drupalci.yml to your project to take advantage of these. Use the suppress-deprecations option to make tests fail on trigger_error() calls. Add the phpstan: step to add static code analyses for deprecations. Here is a sample drupalci.yml snippet:

build:
  assessment:
    validate_codebase:
      # Static analysis of code for @deprecated uses.
      phpstan:
        halt-on-fail: false
    testing:
      run_tests.standard:
        types: 'Simpletest,PHPUnit-Unit,PHPUnit-Kernel,PHPUnit-Functional'
        # Fails on trigger_error(..., E_USER_DEPRECATED) calls encountered.
        suppress-deprecations: false

Automated deprecation fixes with Rector

Dezső Biczó built an initial version of automated deprecation fixes for some common cases with Rector. This was later taken over by Palantir.net. Plans include building coverage for most deprecated APIs. The Upgrade Rector contributed project was built to provide a user interface on top of drupal-rector. It is also integrated with Upgrade Status.

Screenshot of Upgrade Rector's standalone UI

Update custom modules and themes with Rector

First, use Upgrade Status to check the compatibility of your custom modules and/or themes.

While on the Upgrade Status report page, you can run a report on your custom modules and themes to identify deprecated code and to see suggested replacements. To do this, select everything under the “Fix manually” accordion and click the "Scan selected" button at the bottom of the page.

The report is useful, but making all of the suggested changes manually may be tedious. The next section will detail how Drupal Rector may be able to make some of these changes for you.

Automatically replace deprecated code using Drupal Rector

Some deprecated code can be replaced automatically using Drupal Rector. Install Drupal Rector according to the documentation on the GitHub repo.

Once installed, preview the changes Drupal Rector will make by providing the path to your custom modules or themes and including the --dry-run flag:

vendor/bin/rector process docroot/modules/custom --dry-run

If you want to make the changes, run the same command without the --dry-run flag:

vendor/bin/rector process docroot/modules/custom

Run Drupal Rector on both your custom modules and themes directories.

Rerun Upgrade Status report and make manual code changes

After running Drupal Rector, rerun the Upgrade Status report on your custom modules and themes. Hopefully you will find that there are less reported changes that need to be made manually.

You will need to make the remaining changes manually based on the recommendations from the report. Before making any changes, export the report as either HTML or text. It’s possible that at some point you will introduce changes that are not support by Drupal 9, but will be supported by Drupal 10, which will temporarily break your site until after you have upgraded Drupal core, which will cause you to lose access to the Upgrade Status report page.

You may also find that despite running Drupal Rector, there are still recommended changes under the “Fix with rector” accordion. Unfortunately you will need to make these changes manually as well.

Uninstall Upgrade Status and Drupal Rector

Once Upgrade Status reports that all custom modules and themes are compatible with Drupal 10, uninstall and remove Upgrade Status and Drupal Rector:

drush pm-uninstall upgrade_status -y
rm rector.php
composer remove palantirnet/drupal-rector drupal/upgrade_status --no-update

Help improve this page

Page status: No known problems

You can: