Preparing for Drupal 12

Drupal 12 requires PHP 8.5.0 or later; the 12.0.x composer.json declares >=8.5.0. PHP 8.6 is not supported (support for it is tracked separately). The official PHP requirements table for Drupal 10.4 to 12.0 reads as follows:

This table gives the Meridian team its first and cheapest preparation step: PHP 8.5 already runs Drupal 11.3 and 11.4. The PHP upgrade can therefore be done on Drupal 11, in production, weeks before the Drupal 12 update, which splits one risky change into two small ones. Do the same for the other infrastructure items (database version, extensions) whenever they are already supported by the current minor.

For password hashing, PHP must be compiled with argon2 support. The official page says that most or all PHP 8.5 installations already include it. Check it on every environment, not only on the developer machine:

The list of algorithms must include 2y (bcrypt) and, for the new default, argon2i and argon2id. If the second command lacks argon2id, the hosting image has to change before the update.

Source: Change record: Default password hashing algorithm is now argon2id

The 12.0.x branch of drupal/core requires Symfony components at ^8.1 (console, dependency-injection, event-dispatcher, http-kernel, routing, validator, yaml and the others), Twig at ^3.28.0, guzzlehttp/guzzle at ^8.0.1 and doctrine/lexer at ^3. The consequences:

The database requirements page and the 12.0.0-beta1 release notes do not list exactly the same values, so both are stated:

Until the final 12.0.0 release settles the PostgreSQL value, a site on PostgreSQL should plan for 18 as the minimum and treat 19 as the version the beta was tested with. Two related changes are worth knowing. Code and tests for database drivers inside the DRUPAL_ROOT/drivers directory were removed, so custom drivers must be provided by a module. The Database Schema Definition API gained support for generated columns.

Apache 2.4.7 or later and nginx remain the supported web servers. IIS support was removed in Drupal 11.0, and hosting Drupal directly on Windows in production has been deprecated since 11.3 (Linux on Windows through WSL is recommended; Windows support for development continues). The .htaccess shipped with the latest security releases of 11.4 and 10.6 swaps assert.active for zend.assertions; re-apply local customizations of scaffold files after every core update, as the upgrade guide asks.

For the full list of server software and the hosting trade-offs see Requirements and hosting.

Two additional removals appear in the beta notes. The Syndicate block plugin, deprecated in 11.2.0 without a replacement, is removed; placements of that block are deleted during the update. The Navigation Top Bar module, removed in 12.0.0-beta2, has to be uninstalled before updating a site to that beta. The 11.4.0 release notes announced Contact, Field Layout, History, Migrate Drupal, Migrate Drupal UI and Telephone for a move to contributed projects; the 12.0.0 notes narrow that statement for the two migrate modules: they are removed and nobody maintains a replacement. The beta1 changelog also moves the text_with_summary field type into its own module; that module stays in core, so it is not in the table, and body fields with a summary keep working after the update.

The Meridian theme was generated with Starterkit, so it has no base theme to replace. A site that was built with base theme: olivero or base theme: stable9, however, must do some work (see the checks below).

Start from a clean branch and a copy of production on DDEV (see Installation with Composer and DDEV). DDEV is also the upgrade guide’s recommendation: "ideally, first perform the update locally". Pin the PHP version that Drupal 12 needs:

Source: DDEV: Config options

The version of Composer matters: the upgrade guide for Drupal 12 recommends Composer 2.9.3 or later. Write down the state of the site before you change anything:

Source: Drush: core:status

Get to the newest 11.x release first, with Drush and Composer. Updating core inside the same major also exercises the configuration export, the database update path and the test suite without the risk of a new major.

Source: Updating Drupal core via Composer

If a site is on 11.2 or earlier, this step is not optional: Drupal 12 will not update from there. After the site runs on 11.4 or later, switch the container to PHP 8.5 (the version table above shows that 11.3 and 11.4 support it) and run the site again. Fix PHP 8.5 deprecation warnings in custom code now; they are independent of Drupal 12.

Compare the enabled extensions with the removal list:

Source: Drush: pm:list

Every line printed is a decision: add the contributed project (and keep the module installed), or replace the feature and uninstall. Search custom code for hard dependencies too: dependencies: [contact] in *.info.yml, base theme: olivero, stable9 in a theme file, \Drupal\search\... classes in a service, and the libraries named earlier.

The Meridian meridian_collection module declares an optional dependency on search for an object search page. A module that declares a dependency on a module that is moved to a contributed project continues to work, as long as the contributed project is in composer.json; otherwise the dependency is reported as missing after the update and the status report shows errors about missing extensions.

Add each contributed project that the previous step identified, using a constraint that allows the new major. The project page on drupal.org shows which release lines exist for Drupal 12.

Source: How to upgrade from Drupal 11 to Drupal 12

The version constraints above are placeholders: read the real release lines on each project page (they are not part of core’s release cycle). Do not run drush pm:uninstall on a module you want to keep.

Upgrade Status is a contributed module that reports whether the next major version can be installed. It checks core compatibility, system requirements of the next version (PHP, database, extensions), contributed projects that need a new release (by combining it with the Update Status module) and, through PHPStan, deprecated API usage in custom and contributed code. It is run against the current site, because most checks no longer work once the old deprecated code is gone. At the time of writing, version 4.3 (stable) supports Drupal 9 to 11, while 5.0 (still in alpha, 5.0.0-alpha3 released 2026-07-02) adds Drupal 12 compatibility and more known rector coverage. Jumping two majors at once is not supported.

Source: Upgrade Status project page

Read the report at Reports > Upgrade Status (/admin/reports/upgrade-status) or run it in CI with Drush. The analysis command has options to skip uninstalled projects, ignore contributed or custom code, and write checkstyle or Code Climate JSON output for a pipeline:

Source: Upgrade Status project page

The report groups results per project. A project with a red line has a deprecated API, a missing core_version_requirement or an incompatible requirement. For contributed projects without a Drupal 12 release, open the project’s issue queue: a patch or a merge request may exist, and the Lenient Composer endpoint can allow installation with a patch (see below).

For modules and themes the key to declare Drupal 12 compatibility is core_version_requirement. Keep the range as wide as the code actually supports:

Source: Let Drupal know about your module with an .info.yml file

Do not write ^10 || ^11 || ^12 unless the code really runs on all three. A module that is 12-only should say ^12. Since Drupal 10 is end of life on 2026-12-09, an internal project can safely start with ^11.3 || ^12. See Module anatomy and info.yml.

Drupal Rector is the tool the official guides name for automatic fixes. It is a set of rules for Rector, covers deprecations from Drupal 8 to 11.4, and is best run on a site that is already on Drupal 10 or later. The 1.0 line is still a beta. Install it as a development dependency, copy its default configuration to the project root and preview before applying:

Source: Drupal Rector

Review every change: Rector rewrites calls but does not know the intent of the code. Run the tests (see Automated testing) after each pass and commit separately, so a reviewer can read mechanical changes and manual ones apart.

The same tool offers a separate rule set that turns procedural hooks into classes with the #[Hook] attribute (HookConvertRector, run with its own configuration after the normal deprecation pass). Converting hooks is optional for Drupal 12, and Meridian should do it only after the upgrade (see Hooks and OOP hooks). Keep in mind that hook_install, hook_uninstall, hook_schema, hook_requirements, hook_update_N and hook_post_update_NAME must stay procedural.

PHP_CodeSniffer with the Drupal standard catches APIs that are not deprecated but changed; after Coder 9, run it again.

Source: Drupal coding standards

Test annotations (@group, @covers, @dataProvider) are not recognised by PHPUnit 12, so custom tests must use attributes. The Cookbook (2023) and older tutorials still show the annotation syntax and PHPUnit 9.5, which no longer runs:

Source: PHPUnit in Drupal

When Upgrade Status is green for everything the site needs, change the Composer requirements. This follows the official 11 to 12 guide: make the settings files writable, move the core packages to 12, update Drush (Drush 14 supports 11.3 and later and 12), run the update, and restore permissions.

Source: How to upgrade from Drupal 11 to Drupal 12

On a site that deploys with drush deploy, the sequence updatedb, config:import, cache:rebuild and deploy hooks runs as part of the release; see Drush and Deployment and CI/CD. If drupal/core is listed explicitly in composer.json, remove it first with composer remove drupal/core --no-update.

When Composer cannot find a solution, the answer is almost always a contributed project without a Drupal 12 release. Ask Composer which package blocks the update, and decide per package:

Source: How to upgrade from Drupal 11 to Drupal 12

Options for a blocking package, from best to worst: update to a release that supports 12; apply the patch or merge request from the module’s issue queue with a Composer patches plugin and record the ticket number in composer.json; use the Drupal Lenient Composer endpoint, which rewrites the metadata of modules that merely have a restrictive core_version_requirement; or remove the module. The Lenient endpoint is a way to test a module that probably works, not a promise that it does; an old module tested only on one major may call removed APIs.

Source: How to upgrade from Drupal 11 to Drupal 12

The allowed-list narrows the exception to one package; never put a wildcard here for convenience. Remove the exception as soon as the project publishes a real release. Packages that Drupal itself used to pin changed too: drupal/core-recommended no longer pins Guzzle, Twig or the Symfony polyfills, so a project that relied on those pins for reproducibility relies on composer.lock instead.

See Logging, status report and troubleshooting for the status report and log tools.