This serves as the entry point to the MediaWiki session handling system. More...

Inheritance diagram for MediaWiki\Session\SessionManager:

[legend]

Collaboration diagram for MediaWiki\Session\SessionManager:

[legend]

Public Member Functions
	__construct ( $options=[])

	getEmptySession (WebRequest $request=null)
	Create a new, empty session.

	getSessionById ( $id, $create=false, WebRequest $request=null)
	Fetch a session by ID.

	getSessionForRequest (WebRequest $request)
	Fetch the session for a request (or a new empty session if none is attached to it)

	getVaryCookies ()
	Return the list of cookies that need varying on.

	getVaryHeaders ()
	Return the HTTP headers that need varying on.

	invalidateSessionsForUser (User $user)
	Invalidate sessions for a user.

	setHookContainer (HookContainer $hookContainer)

	setLogger (LoggerInterface $logger)

Static Public Member Functions
static	getGlobalSession ()
	If PHP's session_id() has been set, returns that session.

static	singleton ()
	Get the global SessionManager.

static	validateSessionId ( $id)
	Validate a session ID.

Internal methods
static	resetCache ()
	Reset the internal caching for unit testing.

	preventSessionsForUser ( $username)
	Prevent future sessions for the user.

	isUserSessionPrevented ( $username)
	Test if a user is prevented.

	getProvider ( $name)
	Get a session provider by name.

	shutdown ()
	Save all active sessions on shutdown.

	getSessionFromInfo (SessionInfo $info, WebRequest $request)
	Create a Session corresponding to the passed SessionInfo.

	deregisterSessionBackend (SessionBackend $backend)
	Deregister a SessionBackend.

	changeBackendId (SessionBackend $backend)
	Change a SessionBackend's ID.

	generateSessionId ()
	Generate a new random session ID.

	setupPHPSessionHandler (PHPSessionHandler $handler)
	Call setters on a PHPSessionHandler.

	logPotentialSessionLeakage (Session $session=null)
	If the same session is suddenly used from a different IP, that's potentially due to a session leak, so log it.

	getProviders ()
	Get the available SessionProviders.

Detailed Description

This serves as the entry point to the MediaWiki session handling system.

Most methods here are for internal use by session handling code. Other callers should only use getGlobalSession and the methods of SessionManagerInterface; the rest of the functionality is exposed via MediaWiki\Session\Session methods.

To provide custom session handling, implement a MediaWiki\Session\SessionProvider.

Storage expectations

The SessionManager should be configured with a very fast storage system that is optimized for holding key-value pairs. It expects:

Low latencies. Session data is read or written to during nearly all web requests from people that have contributed to or otherwise engaged with the site, including those not logged in with a registered account.
Locally writable data. The data must be writable from both primary and secondary data centres.
Locally latest reads. Writes must by default be immediately consistent within the local data centre, and visible to other reads from web servers in that data centre.
Replication. The data must be eventually consistent across all data centres. Writes are either synced to all remote data centres, or locally overwritten by another write that is.

The SessionManager uses set() and delete() for write operations, which should be synchronous in the local data centre, and replicate asynchronously to any others.

Since: 1.27

See also: https://www.mediawiki.org/wiki/Manual:SessionManager_and_AuthManager

Definition at line 78 of file SessionManager.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Session\SessionManager::__construct ( $options = [] )

Parameters

array

$options

config: Config to fetch configuration from. Defaults to the default 'main' config.
logger: LoggerInterface to use for logging. Defaults to the 'session' channel.
store: BagOStuff to store session data in.

Definition at line 182 of file SessionManager.php.

References MediaWiki\MediaWikiServices\getInstance(), and MediaWiki\MainConfigNames\SessionCacheType.

Member Function Documentation

◆ changeBackendId()

MediaWiki\Session\SessionManager::changeBackendId ( SessionBackend $backend )

Change a SessionBackend's ID.

Access: internal: For use from \MediaWiki\Session\SessionBackend only

Parameters

SessionBackend $backend

Definition at line 966 of file SessionManager.php.

References MediaWiki\Session\SessionBackend\getSessionId().

◆ deregisterSessionBackend()

MediaWiki\Session\SessionManager::deregisterSessionBackend ( SessionBackend $backend )

Deregister a SessionBackend.

Access: internal: For use from \MediaWiki\Session\SessionBackend only

Parameters

SessionBackend $backend

Definition at line 948 of file SessionManager.php.

References MediaWiki\Session\SessionBackend\getId(), and MediaWiki\Session\SessionBackend\getSessionId().

◆ generateSessionId()

MediaWiki\Session\SessionManager::generateSessionId ( )

Generate a new random session ID.

Returns: string

Definition at line 988 of file SessionManager.php.

References MWCryptRand\generateHex().

◆ getEmptySession()

MediaWiki\Session\SessionManager::getEmptySession ( WebRequest $request = null )

Create a new, empty session.

The first provider configured that is able to provide an empty session will be used.

Parameters

WebRequest | null $request Corresponding request. Any existing session associated with this WebRequest object will be overwritten.

Returns: Session

Implements MediaWiki\Session\SessionManagerInterface.

Definition at line 295 of file SessionManager.php.

◆ getGlobalSession()

static MediaWiki\Session\SessionManager::getGlobalSession ( )

static

If PHP's session_id() has been set, returns that session.

Otherwise returns the session for RequestContext::getMain()->getRequest().

Returns: Session

Definition at line 141 of file SessionManager.php.

◆ getProvider()

MediaWiki\Session\SessionManager::getProvider ( $name )

Get a session provider by name.

Generally, this will only be used by internal implementation of some special session-providing mechanism. General purpose code, if it needs to access a SessionProvider at all, will use Session::getProvider().

Parameters

string $name

Returns: SessionProvider|null

Definition at line 505 of file SessionManager.php.

◆ getProviders()

MediaWiki\Session\SessionManager::getProviders ( )

protected

Get the available SessionProviders.

Returns: SessionProvider[]

Definition at line 471 of file SessionManager.php.

References MediaWiki\MediaWikiServices\getInstance(), MediaWiki\Session\SessionProvider\init(), and MediaWiki\MainConfigNames\SessionProviders.

◆ getSessionById()

MediaWiki\Session\SessionManager::getSessionById	(		$id,
			$create = false,
		WebRequest	$request = null )

Fetch a session by ID.

Parameters

string	$id
bool	$create	If no session exists for $id, try to create a new one. May still return null if a session for $id exists but cannot be loaded.
WebRequest \| null	$request	Corresponding request. Any existing session associated with this WebRequest object will be overwritten.

Returns: Session|null

Implements MediaWiki\Session\SessionManagerInterface.

Definition at line 253 of file SessionManager.php.

References MediaWiki\Session\SessionInfo\MIN_PRIORITY.

◆ getSessionForRequest()

MediaWiki\Session\SessionManager::getSessionForRequest ( WebRequest $request )

Fetch the session for a request (or a new empty session if none is attached to it)

Note: You probably want to use $request->getSession() instead. It's more efficient and doesn't break FauxRequests or sessions that were changed by $this->getSessionById() or $this->getEmptySession().

Parameters

WebRequest $request Any existing associated session will be reset to the session corresponding to the data in the request itself.

Returns: Session

Exceptions

\OverflowException if there are multiple sessions tied for top priority in the request. Exception has a property "sessionInfos" holding the SessionInfo objects for the sessions involved.

Implements MediaWiki\Session\SessionManagerInterface.

Definition at line 242 of file SessionManager.php.

◆ getSessionFromInfo()

MediaWiki\Session\SessionManager::getSessionFromInfo	(	SessionInfo	$info,
		WebRequest	$request )

Create a Session corresponding to the passed SessionInfo.

Access: internal: For use by a SessionProvider that needs to specially create its own Session. Most session providers won't need this.

Parameters

SessionInfo	$info
WebRequest	$request

Returns: Session

Definition at line 889 of file SessionManager.php.

References MediaWiki\Session\SessionInfo\getId(), MediaWiki\Session\SessionInfo\isIdSafe(), MW_ENTRY_POINT, MW_NO_SESSION, MediaWiki\MainConfigNames\ObjectCacheSessionExpiry, WebRequest\setSessionId(), MediaWiki\Session\SessionInfo\wasPersisted(), and MediaWiki\Session\SessionInfo\wasRemembered().

◆ getVaryCookies()

MediaWiki\Session\SessionManager::getVaryCookies ( )

Return the list of cookies that need varying on.

Returns: string[]

Implements MediaWiki\Session\SessionManagerInterface.

Definition at line 410 of file SessionManager.php.

References MW_NO_SESSION.

◆ getVaryHeaders()

MediaWiki\Session\SessionManager::getVaryHeaders ( )

Return the HTTP headers that need varying on.

The return value is such that someone could theoretically do this:

foreach ( $provider->getVaryHeaders() as $header => $options ) {
  $outputPage->addVaryHeader( $header, $options );
}

Note that the $options argument to OutputPage::addVaryHeader() has been deprecated and should always be null.

Returns: array

Implements MediaWiki\Session\SessionManagerInterface.

Definition at line 390 of file SessionManager.php.

References $header, and MW_NO_SESSION.

◆ invalidateSessionsForUser()

MediaWiki\Session\SessionManager::invalidateSessionsForUser ( User $user )

Invalidate sessions for a user.

After calling this, existing sessions should be invalid. For mutable session providers, this generally means the user has to log in again; for immutable providers, it generally means the loss of session data.

Parameters

User $user

Implements MediaWiki\Session\SessionManagerInterface.

Definition at line 381 of file SessionManager.php.

References User\saveSettings(), and User\setToken().

◆ isUserSessionPrevented()

MediaWiki\Session\SessionManager::isUserSessionPrevented ( $username )

Test if a user is prevented.

Access: internal: For use from SessionBackend only

Parameters

string $username

Returns: bool

Definition at line 463 of file SessionManager.php.

◆ logPotentialSessionLeakage()

MediaWiki\Session\SessionManager::logPotentialSessionLeakage ( Session $session = null )

If the same session is suddenly used from a different IP, that's potentially due to a session leak, so log it.

In the vast majority of cases it is a false positive due to a user switching connections, but we are interested in an audit track where we can look up a specific username, so a noisy log is fine. Also log changes to the mwuser cookie, an analytics cookie set by mediawiki.user.js which should be a little less noisy.

Access: private: For use in Setup.php only

Parameters

Session | null $session For testing only

Definition at line 1048 of file SessionManager.php.

References MediaWiki\MediaWikiServices\getInstance(), and MediaWiki\MainConfigNames\SuspiciousIpExpiry.

◆ preventSessionsForUser()

MediaWiki\Session\SessionManager::preventSessionsForUser ( $username )

Prevent future sessions for the user.

The intention is that the named account will never again be usable for normal login (i.e. there is no way to undo the prevention of access).

Access: internal: For use from \User::newSystemUser only

Parameters

string $username

Definition at line 448 of file SessionManager.php.

◆ resetCache()

static MediaWiki\Session\SessionManager::resetCache ( )

static

Reset the internal caching for unit testing.

Note: Unit tests only

Access: internal

Definition at line 1010 of file SessionManager.php.

◆ setHookContainer()

MediaWiki\Session\SessionManager::setHookContainer ( HookContainer $hookContainer )

Access: internal

Parameters

HookContainer $hookContainer

Definition at line 237 of file SessionManager.php.

◆ setLogger()

MediaWiki\Session\SessionManager::setLogger ( LoggerInterface $logger )

Definition at line 229 of file SessionManager.php.

◆ setupPHPSessionHandler()

MediaWiki\Session\SessionManager::setupPHPSessionHandler ( PHPSessionHandler $handler )

Call setters on a PHPSessionHandler.

Access: internal: Use PhpSessionHandler::install()

Parameters

PHPSessionHandler $handler

Definition at line 1001 of file SessionManager.php.

References MediaWiki\Session\PHPSessionHandler\setManager().

◆ shutdown()

MediaWiki\Session\SessionManager::shutdown ( )

Save all active sessions on shutdown.

Access: internal: For internal use with register_shutdown_function()

Definition at line 514 of file SessionManager.php.

◆ singleton()

static MediaWiki\Session\SessionManager::singleton ( )

static

Get the global SessionManager.

Returns: self

Definition at line 128 of file SessionManager.php.

◆ validateSessionId()

static MediaWiki\Session\SessionManager::validateSessionId ( $id )

static

Validate a session ID.

Parameters

string $id

Returns: bool

Definition at line 431 of file SessionManager.php.

Referenced by MediaWiki\Session\SessionInfo\__construct(), MediaWiki\Session\ImmutableSessionProviderWithCookie\getSessionIdFromCookie(), and MediaWiki\Session\CookieSessionProvider\provideSessionInfo().

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

includes/session/SessionManager.php

Public Member Functions

Static Public Member Functions

Internal methods

Detailed Description

Storage expectations

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ changeBackendId()

◆ deregisterSessionBackend()

◆ generateSessionId()

◆ getEmptySession()

◆ getGlobalSession()

◆ getProvider()

◆ getProviders()

◆ getSessionById()

◆ getSessionForRequest()

◆ getSessionFromInfo()

◆ getVaryCookies()

◆ getVaryHeaders()

◆ invalidateSessionsForUser()

◆ isUserSessionPrevented()

◆ logPotentialSessionLeakage()

◆ preventSessionsForUser()

◆ resetCache()

◆ setHookContainer()

◆ setLogger()

◆ setupPHPSessionHandler()

◆ shutdown()

◆ singleton()

◆ validateSessionId()