Manual:Hooks/SessionMetadata
| SessionMetadata | |
|---|---|
| Available from version 1.27.0 (Gerrit change 243223) Add metadata to a session being saved | |
| Define function: | public static function onSessionMetadata( $backend, &$metadata, $requests ) { ... }
|
| Attach hook: | In extension.json:
{
"Hooks": {
"SessionMetadata": "MediaWiki\\Extension\\MyExtension\\Hooks::onSessionMetadata"
}
}
|
| Called from: | File(s): session/SessionBackend.php Function(s): save |
| Interface: | SessionMetadataHook.php |
For more information about attaching hooks, see Manual:Hooks.
For examples of extensions using this hook, see Category:SessionMetadata extensions.
Details
edit- Parameters
$backend: SessionBackend being saved.&$metadata: Array of metadata to be stored. Add new keys here. Must be serializable.$requests: Array of WebRequests potentially being saved to. Generally 0-1 real request and 0+ FauxRequests.
- What is allowed
- adding extra metadata to the session is allowed
- What is not allowed
- changing existing keys is not allowed
The metadata can be used to invalidate the session via the SessionCheckInfo hook (e.g. to tie sessions to IPs, one could add the IP address in SessionMetadata and check it against the actual IP address of the request in SessionCheckInfo).
A SessionProvider adding metadata for its own session does not need this hook; it should instead pass the metadata to the SessionInfo constructor, or call SessionBackend::setProviderMetadata(), or use its mergeMetadata() or refreshSessionInfo() methods (which will be called on every request) to update existing metadata.
The default keys in $metadata are:
provider(string) - the classname of the SessionProviderproviderMetadata(array|null) - metadata from the provideruserId(int)userName(string)userToken(string)remember(bool) - "remember me" flag for this sessionforceHTTPS(bool) - whether the user should be forced to use HTTPS.- note there is also a global configuration called Manual:$wgForceHTTPS
expires(int) - time of expiry as a Unix timestamploggedOut(int|null) - Unix timestamp of when the user logged out (for a session that's anonymous but was logged-in earlier)persisted(bool) - whether the session is persisted (ie. the next request from the client will be recognized as belonging to the same session). Typically this means whether the session cookie has been set (or at least added to the current response).
Troubleshooting
editIf you get one of these exceptions thrown from the class SessionBackend:
UnexpectedValueException: SessionMetadata hook changed metadata key "provider" UnexpectedValueException: SessionMetadata hook changed metadata key "providerMetadata" UnexpectedValueException: SessionMetadata hook changed metadata key "userId" UnexpectedValueException: SessionMetadata hook changed metadata key "userName" UnexpectedValueException: SessionMetadata hook changed metadata key "userToken" UnexpectedValueException: SessionMetadata hook changed metadata key "remember" UnexpectedValueException: SessionMetadata hook changed metadata key "forceHTTPS" UnexpectedValueException: SessionMetadata hook changed metadata key "expires" UnexpectedValueException: SessionMetadata hook changed metadata key "loggedOut" UnexpectedValueException: SessionMetadata hook changed metadata key "persisted"
It means these metadata were changed in the hook and they shouldn't.
To change already-existing keys, use dedicated methods instead. Look at the class SessionBackend.