Upgrading from Drupal 9 to Drupal 10 requires preparation. These pointers will help you navigate the major version update and handle contrib and custom modules.

by
saul.willers
/ 23 March 2023Changes from Drupal 9 to Drupal 10

Like the jump from Drupal 8 to Drupal 9, there is no need to rebuild and migrate your data. Drupal 10 is an incremental update. However, it does include some new features.

Updated platform requirements

Noticeably Drupal 10 requires PHP 8.1+. You should make these platform updates before starting the Drupal 10 upgrade. Review the full requirement here.

Third-party dependencies

Under the hood, Drupal 10 has bumped to Symfony 6.2, Guzzle 7.5, and Twig 3, among many others.

Additionally, Drupal 10 requires Drush 11 or later.

Preparing your site

You'll need to take a few steps to prepare your site before the Drupal 10 upgrade.

Upgrade Drupal core to 9.5

Ensuring you're on the latest Drupal 9 core release (currently 9.5.5) before updating to 10 will help smooth the process.

Update all contrib modules

Make sure all contributed modules are on their latest Drupal 9 compatible releases.

In preparation for Drupal 10 an easy way to see which modules and their dependencies will hold you back is to use:

composer why-not drupal/core ^10

An alternative to this is to use Acquia's Drupal 10 Deprecation Status site or the Upgrade Status module.

Helping to get contrib modules ready for Drupal 10 is also a great opportunity to contribute to Drupal. 

Handling contrib modules that aren't ready

Contrib modules that aren't yet compatible with Drupal 10 will need special handling.

Matt Glaman's composer-drupal-lenient is a useful tool that lets you use Drupal 9 compatible modules, then use cweagans/composer-patches to patch them to add Drupal 10 compatibility.

Update custom modules

Using Matt Glaman's excellent phpstan-drupal will ensure your custom code isn't using any deprecated code. It's a great idea to run this on your CI environment to catch deprecations as they're added. If you're uncomfortable with the command line, the Upgrade Status module should help.

Common things to look out for are:

• ->accessCheck() must now be specified on all content entity queries.
• The jquery dependency on once has been removed and is now core/once.
• Test setUp() methods need a void return type (i.e. protected function setUp(): void, and test $modules visibility should be protected (i.e. protected static $modules).
• Twig output using {% spaceless %} has also changed and is now {% apply spaceless %}.

You can then specify your custom modules are compatible with Drupal 10 and above. Going forward, as you update your module with Drupal 11+ compatibility, you shouldn't need to change this again:

core_version_requirement: '>=10'CKEditor

CKEditor in Drupal 10 has received a lot of work and is built on CKEditor 5. The upgrade path should be smooth if your site uses a fairly standard editor configuration.

If you've got a lot of custom editor integration, you might consider using the CKEditor 4 contrib module. Though that is EOL before 2024, so you'll need a plan for this in the near future.

Update to Drupal 10!

You should now be ready to update to Drupal 10. First, in composer.json update your core version: "drupal/core": "^10". Also, update any contrib module versions if they have releases that are only for Drupal 10 and above.

Then run:

composer update --with-all-dependencies

If you experience issues using composer why-not drupal/core ^10 should help you get to the bottom of them.

Finally, run database updates and update your config export, and you should be finished. 

Now, go and run your tests!