Immutable value object returned by SessionProvider. More...

Inherits Stringable.

Collaboration diagram for MediaWiki\Session\SessionInfo:

Public Member Functions
	__construct ( $priority, array $data)

	__toString ()

	forceHTTPS ()
	Whether this session should only be used over HTTPS.

	forceUse ()
	Force use of this SessionInfo if validation fails.

	getId ()
	Return the session ID.

	getPriority ()
	Return the priority.

	getProvider ()
	Return the provider.

	getProviderMetadata ()
	Return provider metadata.

	getUserInfo ()
	Return the user.

	isIdSafe ()
	Indicate whether the ID is "safe".

	needsRefresh ()
	Indicate that the session metadata needs to be re-persisted.

	wasPersisted ()
	Return whether the session is persisted.

	wasRemembered ()
	Return whether the user was remembered.

Static Public Member Functions
static	compare ( $a, $b)
	Compare two SessionInfo objects by priority.

Public Attributes
const	MAX_PRIORITY = 100
	Maximum allowed priority.

const	MIN_PRIORITY = 1
	Minimum allowed priority.

Detailed Description

Immutable value object returned by SessionProvider.

Holds the data necessary to construct a Session.

There are two stages of constructing a Session, which use a potentially different info object:

a SessionProvider will return a SessionInfo based on information in the request (and possibly some checks that do not involve the session store, such as DB lookups)
SessionManager will look up the session ID in the session store, verify the contents of the SessionInfo, and pass an updated SessionInfo to SessionManager::getSessionFromInfo()

Stability: newable

Since: 1.27

Definition at line 26 of file SessionInfo.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Session\SessionInfo::__construct	(		$priority,
		array	$data )

Stability: stable: to call

Parameters

int	$priority	Session priority
array	$data	provider: (SessionProvider\|null) If not given, the provider will be determined from the saved session data. id: (string\|null) Session ID userInfo: (UserInfo\|null) User known from the request. Null means the request contained no user information (e.g. session ID only) and we'll need to rely on the metadata in the session store. An unverified UserInfo means the request contained a username or similar easily forgeable data, and should only result in a valid session if the user information in the session store matches. A verified UserInfo means the request contained some unforgeable proof of user identity, and should be accepted even if there is no metadata in the session store. When the UserInfo is verified and the session store metadata is present but does not match, behavior is governed by the 'forceUse' flag. persisted: (bool) Whether this session was persisted remembered: (bool) Whether the verified user used the "remember me" option during login, which should result in longer login lifetimes. Only meaningful when the UserInfo is verified (as the longer lifetime means we can't rely on the session store for verification). Defaults to true. forceHTTPS: (bool) Whether to force HTTPS for this session. This is ignored if $wgForceHTTPS is true. metadata: (array) Provider metadata, to be returned by Session::getProviderMetadata(). See SessionProvider::mergeMetadata() and SessionProvider::refreshSessionInfo(). idIsSafe: (bool) Set true if the 'id' did not come from the user. Generally you'll use this from SessionProvider::newEmptySession(), and not from any other method. needsRefresh: (bool, since 1.45) Set to true if the session metadata needs to be re-persisted for some reason. This will result in Session::save() being called. forceUse: (bool) Set true if the 'id' is from SessionProvider::hashToSessionId() to delete conflicting session store data instead of discarding this SessionInfo. Ignored unless both 'provider' and 'id' are given. copyFrom: (SessionInfo) SessionInfo to copy other data items from.

Definition at line 105 of file SessionInfo.php.

References MediaWiki\Session\SessionInfo\forceHTTPS(), MediaWiki\Session\SessionInfo\forceUse(), MediaWiki\Session\SessionInfo\needsRefresh(), and MediaWiki\Session\SessionManager\validateSessionId().

Member Function Documentation

◆ __toString()

MediaWiki\Session\SessionInfo::__toString ( )

Definition at line 301 of file SessionInfo.php.

Referenced by MediaWiki\Session\BotPasswordSessionProvider\refreshSessionInfo().

◆ compare()

static MediaWiki\Session\SessionInfo::compare	(		$a,
			$b )

static

Compare two SessionInfo objects by priority.

Parameters

SessionInfo	$a
SessionInfo	$b

Returns: int Negative if $a < $b, positive if $a > $b, zero if equal

Definition at line 313 of file SessionInfo.php.

◆ forceHTTPS()

MediaWiki\Session\SessionInfo::forceHTTPS ( )

final

Whether this session should only be used over HTTPS.

This should be ignored if $wgForceHTTPS is true.

Returns: bool

Definition at line 297 of file SessionInfo.php.

Referenced by MediaWiki\Session\SessionInfo\__construct(), and MediaWiki\Session\SessionBackend\__construct().

◆ forceUse()

MediaWiki\Session\SessionInfo::forceUse ( )

final

Force use of this SessionInfo if validation fails.

The normal behavior is to discard the SessionInfo if validation against the data stored in the session store fails. If this returns true, SessionManager will instead delete the session store data so this SessionInfo may still be used. This is important for providers which use deterministic IDs and so cannot just generate a random new one.

Returns: bool

Definition at line 236 of file SessionInfo.php.

Referenced by MediaWiki\Session\SessionInfo\__construct().

◆ getId()

MediaWiki\Session\SessionInfo::getId ( )

final

Return the session ID.

Returns: string

Definition at line 195 of file SessionInfo.php.

Referenced by MediaWiki\Session\SessionBackend\__construct(), MediaWiki\Session\SessionManager\getSessionFromInfo(), and MediaWiki\Session\MultiBackendSessionStore\set().

◆ getPriority()

MediaWiki\Session\SessionInfo::getPriority ( )

final

Return the priority.

Returns: int

Definition at line 244 of file SessionInfo.php.

Referenced by MediaWiki\Session\SessionBackend\__construct(), and MediaWiki\Session\JwtSessionCookieHelper\verifyJwtCookie().

◆ getProvider()

MediaWiki\Session\SessionInfo::getProvider ( )

final

Return the provider.

Returns: SessionProvider|null

Definition at line 187 of file SessionInfo.php.

Referenced by MediaWiki\Session\SessionBackend\__construct(), and MediaWiki\Session\JwtSessionCookieHelper\verifyJwtCookie().

◆ getProviderMetadata()

MediaWiki\Session\SessionInfo::getProviderMetadata ( )

final

Return provider metadata.

Returns: array|null

Definition at line 268 of file SessionInfo.php.

Referenced by MediaWiki\Session\SessionBackend\__construct().

◆ getUserInfo()

MediaWiki\Session\SessionInfo::getUserInfo ( )

final

Return the user.

Returns: UserInfo|null

Definition at line 252 of file SessionInfo.php.

Referenced by MediaWiki\Session\SessionBackend\__construct(), MediaWiki\Session\BotPasswordSessionProvider\refreshSessionInfo(), and MediaWiki\Session\JwtSessionCookieHelper\verifyJwtCookie().

◆ isIdSafe()

MediaWiki\Session\SessionInfo::isIdSafe ( )

final

Indicate whether the ID is "safe".

The ID is safe in the following cases:

The ID was randomly generated by the constructor.
The ID was found in the backend data store.
$this->getProvider()->persistsSessionId() is false (the client cannot be manipulated into using an arbitrary session ID).
The constructor was explicitly told it's safe using the 'idIsSafe' parameter.

Returns: bool

Definition at line 212 of file SessionInfo.php.

Referenced by MediaWiki\Session\SessionManager\getSessionFromInfo().

◆ needsRefresh()

MediaWiki\Session\SessionInfo::needsRefresh ( )

final

Indicate that the session metadata needs to be re-persisted.

This will result in Session::save() being called.

Since: 1.45

Definition at line 221 of file SessionInfo.php.

Referenced by MediaWiki\Session\SessionInfo\__construct(), and MediaWiki\Session\SessionManager\getSessionFromInfo().

◆ wasPersisted()

MediaWiki\Session\SessionInfo::wasPersisted ( )

final

Return whether the session is persisted.

Returns: bool

Definition at line 260 of file SessionInfo.php.

Referenced by MediaWiki\Session\SessionBackend\__construct(), MediaWiki\Session\SessionManager\getSessionFromInfo(), and MediaWiki\Session\JwtSessionCookieHelper\verifyJwtCookie().

◆ wasRemembered()

MediaWiki\Session\SessionInfo::wasRemembered ( )

final

Return whether the user was remembered.

For providers that can persist the user separately from the session, the human using it may not actually want that to be done. For example, a cookie-based provider can set cookies that are longer-lived than the backend session data, but on a public terminal the human likely doesn't want those cookies set.

This is false unless a non-anonymous verified user was passed to the SessionInfo constructor by the provider, and the provider didn't pass false for the 'remembered' data item.

Returns: bool

Definition at line 287 of file SessionInfo.php.

Referenced by MediaWiki\Session\SessionBackend\__construct(), and MediaWiki\Session\SessionManager\getSessionFromInfo().

Member Data Documentation

◆ MAX_PRIORITY

const MediaWiki\Session\SessionInfo::MAX_PRIORITY = 100

Maximum allowed priority.

Definition at line 31 of file SessionInfo.php.

Referenced by MediaWiki\Session\BotPasswordSessionProvider\__construct(), MediaWiki\Session\CookieSessionProvider\__construct(), and MediaWiki\Session\BotPasswordSessionProvider\newSessionForRequest().

◆ MIN_PRIORITY

const MediaWiki\Session\SessionInfo::MIN_PRIORITY = 1

Minimum allowed priority.

Definition at line 28 of file SessionInfo.php.

Referenced by MediaWiki\Session\SessionProvider\__construct(), MediaWiki\Session\BotPasswordSessionProvider\__construct(), and MediaWiki\Session\CookieSessionProvider\__construct().

The documentation for this class was generated from the following file:

includes/Session/SessionInfo.php

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ __toString()

◆ compare()

◆ forceHTTPS()

◆ forceUse()

◆ getId()

◆ getPriority()

◆ getProvider()

◆ getProviderMetadata()

◆ getUserInfo()

◆ isIdSafe()

◆ needsRefresh()

◆ wasPersisted()

◆ wasRemembered()

Member Data Documentation

◆ MAX_PRIORITY

◆ MIN_PRIORITY