Architecture¶
For example, Claire holds Toggler, Editor and Administrator, and switched Administrator off. On each of her requests:
- Core's cookie provider authenticates her as usual.
- The module's decorator of the
authenticationservice finds Administrator in the session's list of roles switched off, and returns aToggledAccountholding Toggler and Editor instead. That account also keeps her original account, with all three roles. - 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_togglercache 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, fromRoleTogglerManager::buildToggleableRoleSetCacheability().user.permissionsdecorator (CacheContext\AccountPermissionsCacheContextDecorator) stops core from foldinguser.permissionsinto theusercontext, 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_offquery 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.