Skip to content

feat: add ReplaceUserRolePermissionFunctionsRector for Drupal 11.5 (#425) - #426

Merged
bbrala merged 4 commits into
mainfrom
feat/user-role-permission-functions-2025089
Nov 8, 2026
Merged

bbrala merged 4 commits into
mainfrom
feat/user-role-permission-functions-2025089

Conversation

@bbrala

@bbrala bbrala commented Sep 19, 2026

Copy link
Copy Markdown
Collaborator

Closes #425.

Adds ReplaceUserRolePermissionFunctionsRector, rewriting the three procedural user role permission helpers deprecated in drupal:11.5.0 and removed in drupal:13.0.0:

  • user_role_grant_permissions() → RoleInterface::grantPermissions()
  • user_role_revoke_permissions() → RoleInterface::revokePermissions()
  • user_role_change_permissions() → RoleInterface::changePermissions()

Issue: https://www.drupal.org/i/2025089 · Change record: https://www.drupal.org/node/3348027

// Before
user_role_grant_permissions('anonymous', ['access content']);

// After
\Drupal\user\Entity\Role::loadOverrideFree('anonymous')
  ?->grantPermissions(['access content'])
  ?->save();

The role is loaded with the static Role::loadOverrideFree() and chained with nullsafe operators — the pattern core itself adopted in media_install() and node_install(). Calls using named arguments, argument unpacking, or an argument count the deprecated functions never had are left untouched.

Why BC-wrapped

Both the static ConfigEntityBase::loadOverrideFree() and the three RoleInterface methods arrive with this deprecation (core e1f2b85d319, https://www.drupal.org/i/3620216), so the rewritten chain would fatal with "Call to undefined method" on Drupal < 11.5. Only the pre-existing storage method ConfigEntityStorage::loadOverrideFree() predates it, which is a different call shape — verified with git grep against e1f2b85d319~1.

First Drupal 11.5 rule

There was no 11.5 set yet, so this also adds config/drupal-11/drupal-11.5-deprecations.php and registers DRUPAL_115 in:

  • src/Set/Drupal11SetList.php
  • config/drupal-11/drupal-11-all-deprecations.php
  • src/Set/DrupalSetProvider.php (composer-based selection — without this a site on drupal/core ^11.5 would never load the rule)

DrupalSetProviderTest gains a data row pinning 11.5 cumulative matching.

Reviewer note: the rule is dormant until core branches 11.5

Core's 11.x branch still reports VERSION = '11.4-dev' while already carrying the 11.5.0 deprecation — the constant is bumped at release-branch time. installedDrupalVersion() normalises that to 11.4.0, so the 11.5.0 gate correctly declines to fire. Running this against today's 11.x-dev yields zero diffs by design. It activates once core reports 11.5.

Validation

Live-tested against D11-compatible contrib with the version overridden to 11.5.0 — 18 files / 57 call sites rewritten, all passing php -l, none missed:

Module Installs Files
commerce 12,633 6
search_api 147,269 3
webform 120,205 2
sitewide_alert 6,635 2
captcha 131,831 1
matomo 19,558 1
pwa 1,784 1
legal 1,388 1
profile 35,554 1

Shapes covered: string literal and variable role IDs, AccountInterface::ANONYMOUS_ROLE / RoleInterface::ANONYMOUS_ID constants, chained $role->id(), multi-line permission arrays, and fully-qualified calls (\user_role_grant_permissions(, as matomo writes it) — that last one came out of reading real contrib and is now pinned by a fixture.

Also verified: idempotent under a two-pass CLI run with importNames enabled (the isInBackwardsCompatibleCall() guard stops the rule re-firing on the call parked in the deprecatedCallable slot).

PHPStan messages captured against drupal/core:11.x-dev and added to docs/coverage-registry.php.

Checks

  • vendor/bin/phpunit — 702 tests, 967 assertions, green
  • composer phpstan — no errors
  • composer fix-style — no changes

user_role_grant_permissions(), user_role_revoke_permissions() and
user_role_change_permissions() are deprecated in drupal:11.5.0 and removed in
drupal:13.0.0 (https://www.drupal.org/i/2025089, change record
https://www.drupal.org/node/3348027). Each call is rewritten to the matching
\Drupal\user\RoleInterface method on a role loaded with
\Drupal\user\Entity\Role::loadOverrideFree(), the nullsafe chain core itself
adopted in media_install() and node_install().

BC-wrapped: the static Role::loadOverrideFree() and the three RoleInterface
methods all arrive with the deprecation itself (core e1f2b85d319,
https://www.drupal.org/i/3620216), so the rewritten chain would fatal with
"Call to undefined method" on Drupal < 11.5.

Calls using named arguments, argument unpacking, or an argument count the
deprecated functions never had are left untouched.

First Drupal 11.5 rule, so it also adds
config/drupal-11/drupal-11.5-deprecations.php and registers DRUPAL_115 in
Drupal11SetList, drupal-11-all-deprecations.php and the composer-based
DrupalSetProvider.

The rule stays dormant until core branches 11.5: core's 11.x branch still
reports VERSION = '11.4-dev' while already carrying the deprecation, so the
version gate correctly declines to fire until then.

Tested: commerce (6 files changed), search_api (3), webform (2),
sitewide_alert (2), captcha (1), matomo (1), pwa (1), legal (1), profile (1)
— 18 files, 57 call sites rewritten, all passing php -l
…services (#431) (#432)

* feat: replace user_login_finalize()/user_logout() with the finalizer services

user_login_finalize() and user_logout() are deprecated in drupal:11.5.0 and
removed in drupal:13.0.0 (https://www.drupal.org/i/2012976, change record
https://www.drupal.org/node/3379194). Core moved both function bodies verbatim
into two new services (drupal-core accb9caa1fc), so the mapping is 1-to-1 and
two FunctionToServiceRector entries cover it:

  user_login_finalize($account)
  -> \Drupal::service(\Drupal\user\LoginFinalizer::class)->finalizeLogin($account)

  user_logout()
  -> \Drupal::service(\Drupal\user\LogoutFinalizer::class)->finalizeLogout()

BC-wrapped: LoginFinalizer and LogoutFinalizer are added by the deprecation
commit itself, so the rewritten call fatals on Drupal < 11.5.

The digest rule guards against named arguments, because the service parameter
is $user where the deprecated function's was $account. That guard is not
reproduced here: no contrib project calls either function with a named or extra
argument, so the generic rector's verbatim argument pass-through is safe. If a
guard is wanted it belongs on FunctionToServiceRector itself, where it would
cover every function-to-service rule at once.

Neither the deprecated functions nor the service methods take a parameter by
reference, so the wrapper emits arrow functions rather than long closures.
Verified idempotent with importNames(true): a second pass is a no-op, and the
void return types produce no phpstan function.void.

* docs: record the PHPStan messages the finalizer rules cover

Captured live against drupal/core 11.x-dev with externalauth and
openid_connect installed, normalised through
scripts/normalize-phpstan-message.php, and folded into
docs/coverage-registry.php.

* feat: add ReplaceFileSaveUploadFunctionsRector for Drupal 11.5 (#434)

file_save_upload(), file_managed_file_save_upload() and
_file_save_upload_from_form() are deprecated in drupal:11.5.0 and removed in
drupal:13.0.0 (https://www.drupal.org/i/3375423, change record
https://www.drupal.org/node/3382414). Core moved each function body into a new
service (drupal-core e8424495f0d) and left the function delegating to it:

  file_save_upload($name, $validators, $destination, $delta, $fileExists)
  -> \Drupal::service(\Drupal\file\Upload\FormFileUploader::class)
       ->saveFormUploadedFiles(...)

  file_managed_file_save_upload($element, $form_state)
  -> \Drupal::service(\Drupal\file\Upload\ManagedFileElementHelper::class)
       ->managedFileSaveUpload(...)

  _file_save_upload_from_form($element, $form_state, $delta, $fileExists)
  -> \Drupal::service(\Drupal\file\Upload\ManagedFileElementHelper::class)
       ->saveFileUploads(...)

Not a FunctionToServiceRector config entry, because the wrapper also normalised
its arguments where the service methods do not. file_save_upload() turned a
FALSE/NULL $destination into 'temporary://' before delegating, and
saveFormUploadedFiles() types that parameter string — a verbatim pass-through
would hand the service a bool and fatal. That is the dominant contrib shape: a
literal FALSE or NULL third argument appears in 47 files across the contrib
index (tmgmt, file_replace, paragraphs_browser, bootstrap_italia, dxpr_theme,
site_verify, micon, ...), so the rector rewrites the literal.

Both functions also ran a legacy int $fileExists through
FileExists::fromLegacyInt(), while the service parameters accept only the enum.
A FileSystemInterface::EXISTS_* constant is already converted by the
drupal-10.3 set, so the only shape left is a bare integer literal; such a call
is skipped rather than rewritten into a TypeError. No contrib project passes
one today.

BC-wrapped: FormFileUploader and ManagedFileElementHelper arrive with the
deprecation itself (git grep at e8424495f0d~1 finds neither), so the rewritten
call fatals on Drupal < 11.5. Neither the deprecated functions nor the service
methods take a parameter by reference, so the wrapper emits arrow functions,
and all three methods return a value, so no phpstan function.void.

Live-tested against D11-compatible contrib on core 11.x-dev: gin_login (27,767
installs), media_entity_file_replace (23,146), tmgmt (11,680), file_replace
(10,008), paragraphs_browser (9,901), responsive_favicons (4,017), gutenberg
(2,790), file_history — 8 call sites rewritten across all three functions,
including the FALSE and NULL destination shapes and a call already using
FileExists::Replace. plupload was a no-change: its only occurrence is an @see
docblock, correctly left alone. Verified idempotent with importNames(true) — a
second pass is a no-op.

PHPSTAN_MESSAGES captured from those modules and normalised with
scripts/normalize-phpstan-message.php; docs/coverage-registry.php regenerated.
@bbrala
bbrala merged commit 223f46b into main Nov 8, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add rector for deprecated user_role_grant/revoke/change_permissions() (Drupal 11.5)

1 participant