Drupal's upgrade model is simple: new APIs arrive in minor releases, old ones are deprecated, and the next major version removes them. That means the work for Drupal 12 is visible today, in your Drupal 11 codebase. Teams that clean up continuously turn major upgrades into routine maintenance.
Step 1: Make deprecations visible in CI
PHPStan with the Drupal extension and deprecation rules reports every deprecated API your custom code uses:
composer require --dev phpstan/phpstan mglaman/phpstan-drupal \
phpstan/phpstan-deprecation-rules phpstan/extension-installer
# phpstan.neon
parameters:
level: 2
paths:
- web/modules/custom
- web/themes/custom
vendor/bin/phpstan analyse
Run it on every pull request. New deprecations then get fixed when the code is written, not years later.
Step 2: Let tools do the mechanical fixes
- Drupal Rector rewrites many deprecated calls automatically.
- Upgrade Status summarizes custom code, contrib readiness and environment requirements in one report.
Step 3: Adopt the modern APIs
PHP attributes for plugins
Drupal has been moving plugin discovery from docblock annotations to native PHP attributes. Use attributes for new plugins and convert existing ones as you touch them:
use Drupal\Core\Block\Attribute\Block;
use Drupal\Core\Block\BlockBase;
use Drupal\Core\StringTranslation\TranslatableMarkup;
#[Block(
id: 'service_highlights',
admin_label: new TranslatableMarkup('Service highlights'),
)]
final class ServiceHighlightsBlock extends BlockBase {
public function build(): array {
return ['#markup' => $this->t('Our services')];
}
}
Object-oriented hooks
Since Drupal 11.1, hooks can be implemented as methods on classes with the #[Hook] attribute, with full dependency injection:
namespace Drupal\my_module\Hook;
use Drupal\Core\Hook\Attribute\Hook;
final class FormHooks {
#[Hook('form_user_login_form_alter')]
public function loginFormAlter(array &$form): void {
$form['#attributes']['class'][] = 'login-form--branded';
}
}
New code should use this pattern; it is easier to test and keeps .module files small.
Step 4: Keep the platform current
Major Drupal releases traditionally raise minimum PHP and Symfony versions. Run the newest PHP version your Drupal 11 release supports, keep database versions current, and you will meet Drupal 12's requirements with minimal change.
Step 5: Reduce your contrib surface
Every contributed module is a dependency that must be ready for Drupal 12. Audit them now: remove unused modules, replace abandoned ones, and contribute fixes upstream for the ones you depend on.
Step 6: Declare compatibility early
Once your custom modules pass deprecation checks, declare them ready for the next major in their .info.yml, for example core_version_requirement: ^11 || ^12, and test them against development releases of Drupal 12 when available.
A maintenance rhythm that works
| Cadence | Task |
|---|---|
| Every pull request | PHPStan deprecation check |
| Every Drupal minor (twice a year) | Update core, run Upgrade Status, fix new deprecations |
| Quarterly | Contrib audit and platform (PHP/database) review |
For the business side of the decision, read Drupal 12 for decision-makers. Need a readiness assessment? Our Drupal team can run one.