MediaWiki  master
MediaWiki\Session\SessionManager Class Reference

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

Inheritance diagram for MediaWiki\Session\SessionManager:
Collaboration diagram for MediaWiki\Session\SessionManager:

Public Member Functions

 __construct ( $options=[])
 
 getEmptySession (WebRequest $request=null)
 Create a new, empty session. More...
 
 getSessionById ( $id, $create=false, WebRequest $request=null)
 Fetch a session by ID. More...
 
 getSessionForRequest (WebRequest $request)
 Fetch the session for a request (or a new empty session if none is attached to it) More...
 
 getVaryCookies ()
 Return the list of cookies that need varying on. More...
 
 getVaryHeaders ()
 Return the HTTP headers that need varying on. More...
 
 invalidateSessionsForUser (User $user)
 Invalidate sessions for a user. More...
 
 setHookContainer (HookContainer $hookContainer)
 
 setLogger (LoggerInterface $logger)
 

Static Public Member Functions

static getGlobalSession ()
 If PHP's session_id() has been set, returns that session. More...
 
static singleton ()
 Get the global SessionManager. More...
 
static validateSessionId ( $id)
 Validate a session ID. More...
 

Private Member Functions

 getEmptySessionInternal (WebRequest $request=null, $id=null)
 

Private Attributes

SessionBackend[] $allSessionBackends = []
 
SessionId[] $allSessionIds = []
 
Config $config
 
HookContainer $hookContainer
 
HookRunner $hookRunner
 
LoggerInterface $logger
 
string[] $preventUsers = []
 
SessionProvider[] $sessionProviders = null
 
CachedBagOStuff null $store
 
UserNameUtils $userNameUtils
 
string[] $varyCookies = null
 
array $varyHeaders = null
 

Static Private Attributes

static Session null $globalSession = null
 
static WebRequest null $globalSessionRequest = null
 
static SessionManager null $instance = null
 

Internal methods

static resetCache ()
 Reset the internal caching for unit testing. More...
 
 preventSessionsForUser ( $username)
 Prevent future sessions for the user. More...
 
 isUserSessionPrevented ( $username)
 Test if a user is prevented. More...
 
 getProvider ( $name)
 Get a session provider by name. More...
 
 shutdown ()
 Save all active sessions on shutdown. More...
 
 getSessionFromInfo (SessionInfo $info, WebRequest $request)
 Create a Session corresponding to the passed SessionInfo. More...
 
 deregisterSessionBackend (SessionBackend $backend)
 Deregister a SessionBackend. More...
 
 changeBackendId (SessionBackend $backend)
 Change a SessionBackend's ID. More...
 
 generateSessionId ()
 Generate a new random session ID. More...
 
 setupPHPSessionHandler (PHPSessionHandler $handler)
 Call setters on a PHPSessionHandler. More...
 
 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. More...
 
 getSessionInfoForRequest (WebRequest $request)
 Fetch the SessionInfo(s) for a request. More...
 
 loadSessionInfoFromStore (SessionInfo &$info, WebRequest $request)
 Load and verify the session info against the store. More...
 
 logUnpersist (SessionInfo $info, WebRequest $request)
 Reset the internal caching for unit testing. More...
 
 getProviders ()
 Get the available SessionProviders. More...
 

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.
  • Support BagOStuff::WRITE_SYNC flag. The data must writable with synchronous replication waited for, across all data centres. This is used when resetting or deleting a session, which must not be lost or overwritten by earlier or overlapping write actions.

The SessionManager uses set() and delete() for write operations, which should by default be synchronous in the local data centre, and replicate asynchronously to any others. This behaviour can be overridden by the use of the WRITE_SYNC flag.

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

Definition at line 83 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 187 of file SessionManager.php.

References MediaWiki\Session\SessionManager\$store, ObjectCache\getInstance(), MediaWiki\MediaWikiServices\getInstance(), MediaWiki\Session\SessionManager\setHookContainer(), and MediaWiki\Session\SessionManager\setLogger().

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 952 of file SessionManager.php.

References MediaWiki\Session\SessionManager\generateSessionId(), and 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 934 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 974 of file SessionManager.php.

References MWCryptRand\generateHex().

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

◆ 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$requestCorresponding request. Any existing session associated with this WebRequest object will be overwritten.
Returns
Session

Implements MediaWiki\Session\SessionManagerInterface.

Definition at line 300 of file SessionManager.php.

References MediaWiki\Session\SessionManager\getEmptySessionInternal().

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

◆ getEmptySessionInternal()

MediaWiki\Session\SessionManager::getEmptySessionInternal ( WebRequest  $request = null,
  $id = null 
)
private

◆ getGlobalSession()

◆ 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 493 of file SessionManager.php.

References MediaWiki\Session\SessionManager\getProviders().

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

◆ getProviders()

◆ getSessionById()

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

Fetch a session by ID.

Parameters
string$id
bool$createIf 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$requestCorresponding request. Any existing session associated with this WebRequest object will be overwritten.
Returns
Session|null

Implements MediaWiki\Session\SessionManagerInterface.

Definition at line 258 of file SessionManager.php.

References MediaWiki\Session\SessionManager\getEmptySessionInternal(), MediaWiki\Session\SessionManager\getSessionFromInfo(), MediaWiki\Session\SessionManager\loadSessionInfoFromStore(), and 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$requestAny existing associated session will be reset to the session corresponding to the data in the request itself.
Returns
Session
Exceptions

Implements MediaWiki\Session\SessionManagerInterface.

Definition at line 247 of file SessionManager.php.

References MediaWiki\Session\SessionManager\getEmptySession(), MediaWiki\Session\SessionManager\getSessionFromInfo(), and MediaWiki\Session\SessionManager\getSessionInfoForRequest().

◆ getSessionFromInfo()

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

◆ getSessionInfoForRequest()

MediaWiki\Session\SessionManager::getSessionInfoForRequest ( WebRequest  $request)
private

◆ getVaryCookies()

MediaWiki\Session\SessionManager::getVaryCookies ( )

Return the list of cookies that need varying on.

Returns
string[]

Implements MediaWiki\Session\SessionManagerInterface.

Definition at line 399 of file SessionManager.php.

References MediaWiki\Session\SessionManager\$varyCookies, MediaWiki\Session\SessionManager\getProviders(), and 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 379 of file SessionManager.php.

References $header, MediaWiki\Session\SessionManager\$varyHeaders, MediaWiki\Session\SessionManager\getProviders(), 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 370 of file SessionManager.php.

References MediaWiki\Session\SessionManager\getProviders(), 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 452 of file SessionManager.php.

◆ loadSessionInfoFromStore()

◆ 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$sessionFor testing only

Definition at line 1034 of file SessionManager.php.

References MediaWiki\Session\SessionManager\$logger, MediaWiki\Session\SessionManager\getGlobalSession(), MediaWiki\Logger\LoggerFactory\getInstance(), and MediaWiki\MediaWikiServices\getInstance().

◆ logUnpersist()

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

◆ 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 437 of file SessionManager.php.

References MediaWiki\Session\SessionManager\getProviders().

◆ resetCache()

static MediaWiki\Session\SessionManager::resetCache ( )
static

Reset the internal caching for unit testing.

Note
Unit tests only
Access: internal

Definition at line 996 of file SessionManager.php.

◆ setHookContainer()

MediaWiki\Session\SessionManager::setHookContainer ( HookContainer  $hookContainer)
Access: internal
Parameters
HookContainer$hookContainer

Definition at line 242 of file SessionManager.php.

References MediaWiki\Session\SessionManager\$hookContainer.

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

◆ setLogger()

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

◆ setupPHPSessionHandler()

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

Call setters on a PHPSessionHandler.

Access: internal
Use PhpSessionHandler::install()
Parameters
PHPSessionHandler$handler

Definition at line 987 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 502 of file SessionManager.php.

◆ singleton()

static MediaWiki\Session\SessionManager::singleton ( )
static

◆ validateSessionId()

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

Member Data Documentation

◆ $allSessionBackends

SessionBackend [] MediaWiki\Session\SessionManager::$allSessionBackends = []
private

Definition at line 121 of file SessionManager.php.

◆ $allSessionIds

SessionId [] MediaWiki\Session\SessionManager::$allSessionIds = []
private

Definition at line 124 of file SessionManager.php.

◆ $config

Config MediaWiki\Session\SessionManager::$config
private

Definition at line 103 of file SessionManager.php.

◆ $globalSession

Session null MediaWiki\Session\SessionManager::$globalSession = null
staticprivate

◆ $globalSessionRequest

WebRequest null MediaWiki\Session\SessionManager::$globalSessionRequest = null
staticprivate

Definition at line 91 of file SessionManager.php.

◆ $hookContainer

HookContainer MediaWiki\Session\SessionManager::$hookContainer
private

◆ $hookRunner

HookRunner MediaWiki\Session\SessionManager::$hookRunner
private

Definition at line 100 of file SessionManager.php.

◆ $instance

SessionManager null MediaWiki\Session\SessionManager::$instance = null
staticprivate

Definition at line 85 of file SessionManager.php.

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

◆ $logger

LoggerInterface MediaWiki\Session\SessionManager::$logger
private

◆ $preventUsers

string [] MediaWiki\Session\SessionManager::$preventUsers = []
private

Definition at line 127 of file SessionManager.php.

◆ $sessionProviders

SessionProvider [] MediaWiki\Session\SessionManager::$sessionProviders = null
private

Definition at line 112 of file SessionManager.php.

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

◆ $store

CachedBagOStuff null MediaWiki\Session\SessionManager::$store
private

Definition at line 109 of file SessionManager.php.

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

◆ $userNameUtils

UserNameUtils MediaWiki\Session\SessionManager::$userNameUtils
private

Definition at line 106 of file SessionManager.php.

◆ $varyCookies

string [] MediaWiki\Session\SessionManager::$varyCookies = null
private

Definition at line 115 of file SessionManager.php.

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

◆ $varyHeaders

array MediaWiki\Session\SessionManager::$varyHeaders = null
private

Definition at line 118 of file SessionManager.php.

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


The documentation for this class was generated from the following file:
$header
$header
Definition: updateCredits.php:37