PHP & Drupal deprecations audit (before a major core bump)

⚠️ RUN WHILE CORE IS STILL ON THE OLD MAJOR (e.g. Drupal 10). Upgrade Status and drupal-rector derive their target from the installed core. On D10 they surface/fix "deprecated in D10, removed in D11" — exactly what we want. If core is already on D11 they switch to the D12 target and the D11 correction list becomes unreachable. Fix everything and re-scan until 0 errors for the target major BEFORE bumping core.

Golden rule: everything goes through the Makefile

Never call drush, composer or php directly on the host — use make:

For tools that must run inside the container (rector, php -v…), use make shell and execute from within.

Main tool: Upgrade Status

drupal/upgrade_status scans custom and contrib code for deprecated APIs and next-major incompatibilities.

make composer-require drupal/upgrade_status --dev
make en upgrade_status
make drush c='upgrade_status:analyze'                 # overview

Report also at /admin/reports/upgrade-status. Target a specific module:

make drush c='upgrade_status:analyze <custom_module_name>'
make drush c='pml --type=module --status=enabled --no-core'

Static analysis with PHPStan

The project has a make phpstan target. Ensure phpstan.neon includes web/modules/custom and web/themes/custom. Recommended for deprecation detection: mglaman/phpstan-drupal + phpstan/phpstan-deprecation-rules.

make phpstan

Automate fixes: Drupal Rector

drupal-rector applies a large share of the corrections automatically. Its config targets the next version relative to the installed core: run on D10 it prepares the code for D11 — which is why it must run before the core bump (on D11 it would target D12).

make composer-require palantirnet/drupal-rector --dev
make shell
# inside the container — dry-run first:
vendor/bin/rector process web/modules/custom --dry-run
# if OK:
vendor/bin/rector process web/modules/custom
exit

Rector doesn't fix everything: re-run make phpstan and upgrade_status afterwards and handle the remainder manually.

Manual scan of custom modules

ls web/modules/custom
grep -rn 'entity.manager\|entityManager(' web/modules/custom
grep -rn 'drupal_set_message' web/modules/custom
grep -rn 'file_unmanaged_' web/modules/custom
grep -rn '\\\\Drupal::url(' web/modules/custom
grep -rn 'node_load(\|user_load(\|taxonomy_term_load(' web/modules/custom

Main D11 removals table

PHP language-level deprecations (not just Drupal APIs)

Rector and Upgrade Status only target removed Drupal APIs — they miss pure PHP deprecations tied to the new runtime (see php-docker-upgrade). Detect these with make phpstan running under the target PHP version.

Implicitly nullable parameters — the frequent PHP 8.4 one

A pure PHP 8.4 deprecation, not a Drupal API change. Rector and Upgrade Status do not report it — a separate phpstan pass is required.

// Before (deprecated in PHP 8.4)
public function buildForm(array $form, FormStateInterface $form_state, Request $request = null) {}

// After (correct)
public function buildForm(array $form, FormStateInterface $form_state, ?Request $request = null) {}
// or
public function buildForm(array $form, FormStateInterface $form_state, Request|null $request = null) {}

Rule: whenever a typed parameter has = null as its default, the type must be explicitly nullable (?Type or Type|null). Frequent on buildForm() and injected optional params.

Detect:

make phpstan 2>&1 | grep -i "implicitly"

# or grep the source directly
grep -rn "function.*\(.*[A-Z][a-zA-Z]*\s\+\$[a-z].*=\s*null" web/modules/custom/ web/themes/custom/

Known contrib affected (watch when updating): field_group, config_ignore. They emit runtime warnings but don't block — report upstream.

Loop until clean

Custom modules live under web/modules/custom. Re-run upgrade_status:analyze after each pass until custom code is declared compatible with the target major. Do not bump core before this reaches 0 errors.

make drush c='upgrade_status:analyze <module>'   # re-scan

Cleanup at the end of the whole upgrade

The upgrade_status and drupal-rector dev dependencies are audit-only — remove them once the core bump is done (handled by the d11 orchestrator, not here):

make pmu upgrade_status
make composer-remove drupal/upgrade_status
make composer-remove palantirnet/drupal-rector