Skip to content

Architecture

For example, Claire holds Toggler, Editor and Administrator, and switched Administrator off. On each of her requests:

  1. Core's cookie provider authenticates her as usual.
  2. The module's decorator of the authentication service finds Administrator in the session's list of roles switched off, and returns a ToggledAccount holding Toggler and Editor instead. That account also keeps her original account, with all three roles.
  3. The current user service holds that account for the rest of the request, so every permission check sees two roles, not three.

The module does not keep the current user's roles itself: the current user tells both the toggled roles and the original ones. When code switches the current user, for example with the account switcher during cron, the module follows.

Her user entity and the database never change.

Swapping the account

Class Role
AuthenticationManager\RoleTogglerAuthenticationManagerDecorator Decorates authentication. After core authenticates, it asks RoleTogglerManager for the roles of this request and, when some are off, returns a ToggledAccount.
AccountDecorator\ToggledAccount Wraps the authenticated account with the toggled roles, and keeps the original account. Its permissions come from those roles through the site's access policies, like any account's. The original account answers for the two toggle permissions, and for the toolbar and navigation ones when the settings keep them.
RoleTogglerManager Works out which roles an account may toggle, reads the roles switched off from the tab's URL or the session, and remembers the user's choice. It reads the current user's original and toggled roles.
RestrictedRoles Tells whether a role is marked Restricted, a third-party setting of the role.
RoleSet An immutable set of roles, sorted by weight.

The anonymous view returns a ToggledAccount that wraps an anonymous session, so the request runs as user 0 while the module still knows who asked.

Keeping the user entity in step

Some code loads the current user's entity rather than asking the current user service. Hook\EntityHooks keeps both in step:

  • hook_entity_load(), first of all implementations, gives the loaded entity the toggled roles.
  • hook_entity_presave(), last of all implementations, puts the original roles back before the user is saved, so toggled roles are never stored.

The load hook acts only on the current user's entity, while the current user holds a ToggledAccount. RoleTogglerManager keeps the own roles of each user it changes, by user ID, so the presave hook puts them back even when a copy of the entity is saved, as entity forms do, or when the current user was switched to another account before the save.

A role that code grants the user during the request, or a toggled role it takes away, is kept: the presave hook compares the entity's roles with the toggled ones it gave, and applies the difference to the user's own roles.

The decorator also updates the copy core may have loaded before authentication, for example for the interface language.

Where the choice lives

Where Key Lifetime
Session simple_role_toggler_switched_off_roles the session
User data module simple_role_toggler, name switched_off_roles until the user chooses all roles, or logs out on purpose
Tab URL roles_off query the tab, when the per-tab setting is on

Hook\UserHooks copies the user data into the new session at login, and deletes it at a voluntary logout when the settings ask for it. Masquerade invokes the same hooks on each switch, so each account keeps its own choice.

Caching

Core's user.roles and user.permissions cache contexts see the toggled roles. Two more pieces cover what they cannot see:

  • simple_role_toggler cache context (CacheContext\OriginalRolesCacheContext) varies by the roles held before toggling. The block and the toolbar item use it, because who may toggle depends on those roles. They get it, with the roles' cache tags, from RoleTogglerManager::buildToggleableRoleSetCacheability().
  • user.permissions decorator (CacheContext\AccountPermissionsCacheContextDecorator) stops core from folding user.permissions into the user context, which does not know about toggled roles.

Rendering

The role form shows the toggled roles, so the toolbar tray and both blocks render it late, in a placeholder of its own. RoleTogglerLazyBuilders (simple_role_toggler.lazy_builders) builds both kinds of placeholder, the form's and the icon's, and renders them.

Cost

  • An anonymous visitor costs no permission check: the block and the cache context see at once that there is nothing to toggle.
  • A user who may not toggle costs two permission checks per request, one per toggle permission.
  • The role sets are built once per account and request, and reused by the toolbar, the blocks, the form and the cache context. A toggled account answers for the toggle permissions from the original account's answers.
  • A toggled account's other permissions come from core's access policy processor. When the policies vary by the user only, the account keeps them for the rest of the request, so each later check is a lookup. When a policy also varies by something else, such as the page, each check asks the processor again.
  • The per-tab mode, when off, costs one lookup in the query string: the settings are read only when a roles_off query is present.
  • The icon's script, which opens its form in a modal dialog, is attached by the icon block only.
  • The per-tab script is attached by the role form only. There is no site-wide subscriber, path processor or form alter.