MediaWiki  REL1_31
MediaWiki\Session\Session Class Reference

Manages data for an an authenticated session. More...

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

Public Member Functions

 __construct (SessionBackend $backend, $index, LoggerInterface $logger)
 
 __destruct ()
 
 canSetUser ()
 Indicate whether the session user info can be changed. More...
 
 clear ()
 Delete all session data and clear the user (if possible) More...
 
 delaySave ()
 Delay automatic saving while multiple updates are being made. More...
 
 exists ( $key)
 Test if a value exists in the session. More...
 
 get ( $key, $default=null)
 Fetch a value from the session. More...
 
 getAllowedUserRights ()
 Fetch the rights allowed the user when this session is active. More...
 
 getId ()
 Returns the session ID. More...
 
 getLoggedOutTimestamp ()
 Fetch the "logged out" timestamp. More...
 
 getProvider ()
 Fetch the SessionProvider for this session. More...
 
 getProviderMetadata ()
 Fetch provider metadata. More...
 
 getRequest ()
 Returns the request associated with this session. More...
 
 getSecret ( $key, $default=null)
 Fetch a value from the session that was set with self::setSecret() More...
 
 getSessionId ()
 Returns the SessionId object. More...
 
 getToken ( $salt='', $key='default')
 Fetch a CSRF token from the session. More...
 
 getUser ()
 Returns the authenticated user for this session. More...
 
 isPersistent ()
 Indicate whether this session is persisted across requests. More...
 
 persist ()
 Make this session persisted across requests. More...
 
 remove ( $key)
 Remove a value from the session. More...
 
 renew ()
 Renew the session. More...
 
 resetAllTokens ()
 Remove all CSRF tokens from the session. More...
 
 resetId ()
 Changes the session ID. More...
 
 resetToken ( $key='default')
 Remove a CSRF token from the session. More...
 
 save ()
 Save the session. More...
 
 sessionWithRequest (WebRequest $request)
 Fetch a copy of this session attached to an alternative WebRequest. More...
 
 set ( $key, $value)
 Set a value in the session. More...
 
 setForceHTTPS ( $force)
 Set the value of the forceHTTPS cookie. More...
 
 setLoggedOutTimestamp ( $ts)
 Set the "logged out" timestamp. More...
 
 setRememberUser ( $remember)
 Set whether the user should be remembered independently of the session ID. More...
 
 setSecret ( $key, $value)
 Set a value in the session, encrypted. More...
 
 setUser ( $user)
 Set a new user for this session. More...
 
 shouldForceHTTPS ()
 Get the expected value of the forceHTTPS cookie. More...
 
 shouldRememberUser ()
 Indicate whether the user should be remembered independently of the session ID. More...
 
 suggestLoginUsername ()
 Get a suggested username for the login form. More...
 
 unpersist ()
 Make this session not be persisted across requests. More...
 
Interface methods
 count ()
 @inheritDoc More...
 
 current ()
 @inheritDoc More...
 
 key ()
 @inheritDoc More...
 
 next ()
 @inheritDoc More...
 
 rewind ()
 @inheritDoc More...
 
 valid ()
 @inheritDoc More...
 
 offsetExists ( $offset)
 
offsetGet ( $offset)
 
 offsetSet ( $offset, $value)
 @inheritDoc More...
 
 offsetUnset ( $offset)
 @inheritDoc More...
 

Private Member Functions

 getSecretKeys ()
 Fetch the secret keys for self::setSecret() and self::getSecret(). More...
 

Static Private Member Functions

static getEncryptionAlgorithm ()
 Decide what type of encryption to use, based on system capabilities. More...
 

Private Attributes

SessionBackend $backend
 Session backend. More...
 
int $index
 Session index. More...
 
LoggerInterface $logger
 

Static Private Attributes

static null string[] $encryptionAlgorithm = null
 Encryption algorithm to use. More...
 

Detailed Description

Manages data for an an authenticated session.

A Session represents the fact that the current HTTP request is part of a session. There are two broad types of Sessions, based on whether they return true or false from self::canSetUser():

  • When true (mutable), the Session identifies multiple requests as part of a session generically, with no tie to a particular user.
  • When false (immutable), the Session identifies multiple requests as part of a session by identifying and authenticating the request itself as belonging to a particular user.

The Session object also serves as a replacement for PHP's $_SESSION, managing access to per-session data.

Since
1.27

Definition at line 48 of file Session.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Session\Session::__construct ( SessionBackend  $backend,
  $index,
LoggerInterface  $logger 
)
Parameters
SessionBackend$backend
int$index
LoggerInterface$logger

Definition at line 66 of file Session.php.

References MediaWiki\Session\Session\$backend, MediaWiki\Session\Session\$index, and MediaWiki\Session\Session\$logger.

◆ __destruct()

MediaWiki\Session\Session::__destruct ( )

Definition at line 72 of file Session.php.

Member Function Documentation

◆ canSetUser()

MediaWiki\Session\Session::canSetUser ( )

Indicate whether the session user info can be changed.

Returns
bool

Definition at line 188 of file Session.php.

◆ clear()

MediaWiki\Session\Session::clear ( )

Delete all session data and clear the user (if possible)

Definition at line 261 of file Session.php.

◆ count()

MediaWiki\Session\Session::count ( )

@inheritDoc

Definition at line 631 of file Session.php.

Referenced by MediaWiki\Session\Session\getSecret().

◆ current()

MediaWiki\Session\Session::current ( )

@inheritDoc

Definition at line 637 of file Session.php.

◆ delaySave()

MediaWiki\Session\Session::delaySave ( )

Delay automatic saving while multiple updates are being made.

Calls to save() or clear() will not be delayed.

Returns
\Wikimedia\ScopedCallback When this goes out of scope, a save will be triggered

Definition at line 611 of file Session.php.

◆ exists()

MediaWiki\Session\Session::exists (   $key)

Test if a value exists in the session.

Note
Unlike isset(), null values are considered to exist.
Parameters
string | int$key
Returns
bool

Definition at line 314 of file Session.php.

◆ get()

MediaWiki\Session\Session::get (   $key,
  $default = null 
)

Fetch a value from the session.

Parameters
string | int$key
mixed$defaultReturned if $this->exists( $key ) would be false
Returns
mixed

Definition at line 303 of file Session.php.

◆ getAllowedUserRights()

MediaWiki\Session\Session::getAllowedUserRights ( )

Fetch the rights allowed the user when this session is active.

Returns
null|string[] Allowed user rights, or null to allow all.

Definition at line 180 of file Session.php.

◆ getEncryptionAlgorithm()

static MediaWiki\Session\Session::getEncryptionAlgorithm ( )
staticprivate

Decide what type of encryption to use, based on system capabilities.

Returns
array

Definition at line 426 of file Session.php.

References MediaWiki\Session\Session\$encryptionAlgorithm, $wgSessionInsecureSecrets, and global.

Referenced by MediaWiki\Session\Session\getSecret(), and MediaWiki\Session\Session\setSecret().

◆ getId()

MediaWiki\Session\Session::getId ( )

Returns the session ID.

Returns
string

Definition at line 80 of file Session.php.

◆ getLoggedOutTimestamp()

MediaWiki\Session\Session::getLoggedOutTimestamp ( )

Fetch the "logged out" timestamp.

Returns
int

Definition at line 237 of file Session.php.

◆ getProvider()

MediaWiki\Session\Session::getProvider ( )

Fetch the SessionProvider for this session.

Returns
SessionProviderInterface

Definition at line 105 of file Session.php.

◆ getProviderMetadata()

MediaWiki\Session\Session::getProviderMetadata ( )

Fetch provider metadata.

Access:\n protected For use by SessionProvider subclasses only
Returns
mixed

Definition at line 254 of file Session.php.

◆ getRequest()

MediaWiki\Session\Session::getRequest ( )

Returns the request associated with this session.

Returns
WebRequest

Definition at line 164 of file Session.php.

◆ getSecret()

MediaWiki\Session\Session::getSecret (   $key,
  $default = null 
)

Fetch a value from the session that was set with self::setSecret()

Parameters
string | int$key
mixed$defaultReturned if $this->exists( $key ) would be false or decryption fails
Returns
mixed

Definition at line 534 of file Session.php.

References $serialized, $value, MediaWiki\Session\Session\count(), MediaWiki\Session\Session\getEncryptionAlgorithm(), MediaWiki\Session\Session\getSecretKeys(), list, serialize(), and unserialize().

◆ getSecretKeys()

MediaWiki\Session\Session::getSecretKeys ( )
private

Fetch the secret keys for self::setSecret() and self::getSecret().

Returns
string[] Encryption key, HMAC key

Definition at line 400 of file Session.php.

References $wgSecretKey, $wgSessionPbkdf2Iterations, $wgSessionSecret, MWCryptRand\generateHex(), and global.

Referenced by MediaWiki\Session\Session\getSecret(), and MediaWiki\Session\Session\setSecret().

◆ getSessionId()

MediaWiki\Session\Session::getSessionId ( )

Returns the SessionId object.

Access:\n private For internal use by WebRequest
Returns
SessionId

Definition at line 89 of file Session.php.

◆ getToken()

MediaWiki\Session\Session::getToken (   $salt = '',
  $key = 'default' 
)

Fetch a CSRF token from the session.

Note that this does not persist the session, which you'll probably want to do if you want the token to actually be useful.

Parameters
string | string[]$saltToken salt
string$keyToken key
Returns
Token

Definition at line 354 of file Session.php.

References MWCryptRand\generateHex().

◆ getUser()

MediaWiki\Session\Session::getUser ( )

Returns the authenticated user for this session.

Returns
User

Definition at line 172 of file Session.php.

◆ isPersistent()

MediaWiki\Session\Session::isPersistent ( )

Indicate whether this session is persisted across requests.

For example, if cookies are set.

Returns
bool

Definition at line 116 of file Session.php.

◆ key()

MediaWiki\Session\Session::key ( )

@inheritDoc

Definition at line 643 of file Session.php.

Referenced by MediaWiki\Session\Session\valid().

◆ next()

MediaWiki\Session\Session::next ( )

@inheritDoc

Definition at line 649 of file Session.php.

◆ offsetExists()

MediaWiki\Session\Session::offsetExists (   $offset)
Note
Despite the name, this seems to be intended to implement isset() rather than array_key_exists(). So do that. @inheritDoc

Definition at line 671 of file Session.php.

◆ offsetGet()

& MediaWiki\Session\Session::offsetGet (   $offset)
Note
This supports indirect modifications but can't mark the session dirty when those happen. SessionBackend::save() checks the hash of the data to detect such changes.
Accessing a nonexistent key via this mechanism causes that key to be created with a null value, and does not raise a PHP warning. @inheritDoc

Definition at line 684 of file Session.php.

◆ offsetSet()

MediaWiki\Session\Session::offsetSet (   $offset,
  $value 
)

@inheritDoc

Definition at line 694 of file Session.php.

References $value.

◆ offsetUnset()

MediaWiki\Session\Session::offsetUnset (   $offset)

@inheritDoc

Definition at line 699 of file Session.php.

◆ persist()

MediaWiki\Session\Session::persist ( )

Make this session persisted across requests.

If the session is already persistent, equivalent to calling $this->renew().

Definition at line 126 of file Session.php.

◆ remove()

MediaWiki\Session\Session::remove (   $key)

Remove a value from the session.

Parameters
string | int$key

Definition at line 336 of file Session.php.

◆ renew()

MediaWiki\Session\Session::renew ( )

Renew the session.

Resets the TTL in the backend store if the session is near expiring, and re-persists the session to any active WebRequests if persistent.

Definition at line 279 of file Session.php.

◆ resetAllTokens()

MediaWiki\Session\Session::resetAllTokens ( )

Remove all CSRF tokens from the session.

Definition at line 392 of file Session.php.

◆ resetId()

MediaWiki\Session\Session::resetId ( )

Changes the session ID.

Returns
string New ID (might be the same as the old)

Definition at line 97 of file Session.php.

◆ resetToken()

MediaWiki\Session\Session::resetToken (   $key = 'default')

Remove a CSRF token from the session.

The next call to self::getToken() with $key will generate a new secret.

Parameters
string$keyToken key

Definition at line 381 of file Session.php.

◆ rewind()

MediaWiki\Session\Session::rewind ( )

@inheritDoc

Definition at line 655 of file Session.php.

◆ save()

MediaWiki\Session\Session::save ( )

Save the session.

This will update the backend data and might re-persist the session if needed.

Definition at line 621 of file Session.php.

◆ sessionWithRequest()

MediaWiki\Session\Session::sessionWithRequest ( WebRequest  $request)

Fetch a copy of this session attached to an alternative WebRequest.

Actions on the copy will affect this session too, and vice versa.

Parameters
WebRequest$requestAny existing session associated with this WebRequest object will be overwritten.
Returns
Session

Definition at line 292 of file Session.php.

References $request.

◆ set()

MediaWiki\Session\Session::set (   $key,
  $value 
)

Set a value in the session.

Parameters
string | int$key
mixed$value

Definition at line 324 of file Session.php.

References $value.

◆ setForceHTTPS()

MediaWiki\Session\Session::setForceHTTPS (   $force)

Set the value of the forceHTTPS cookie.

This reflects whether session cookies were sent with the Secure attribute. If $wgForceHTTPS is true, the forceHTTPS cookie is not sent, and this value is ignored.

Parameters
bool$force

Definition at line 229 of file Session.php.

◆ setLoggedOutTimestamp()

MediaWiki\Session\Session::setLoggedOutTimestamp (   $ts)

Set the "logged out" timestamp.

Parameters
int$ts

Definition at line 245 of file Session.php.

◆ setRememberUser()

MediaWiki\Session\Session::setRememberUser (   $remember)

Set whether the user should be remembered independently of the session ID.

Parameters
bool$remember

Definition at line 156 of file Session.php.

◆ setSecret()

MediaWiki\Session\Session::setSecret (   $key,
  $value 
)

Set a value in the session, encrypted.

This relies on the secrecy of $wgSecretKey (by default), or $wgSessionSecret.

Parameters
string | int$key
mixed$value

Definition at line 481 of file Session.php.

References $serialized, $value, MWCryptRand\generate(), MediaWiki\Session\Session\getEncryptionAlgorithm(), MediaWiki\Session\Session\getSecretKeys(), list, and serialize().

◆ setUser()

MediaWiki\Session\Session::setUser (   $user)

Set a new user for this session.

Note
This should only be called when the user has been authenticated
Parameters
User$userUser to set on the session. This may become a "UserValue" in the future, or User may be refactored into such.

Definition at line 199 of file Session.php.

References $user.

◆ shouldForceHTTPS()

MediaWiki\Session\Session::shouldForceHTTPS ( )

Get the expected value of the forceHTTPS cookie.

This reflects whether session cookies were sent with the Secure attribute. If $wgForceHTTPS is true, the forceHTTPS cookie is not sent and this value is ignored.

Returns
bool

Definition at line 218 of file Session.php.

◆ shouldRememberUser()

MediaWiki\Session\Session::shouldRememberUser ( )

Indicate whether the user should be remembered independently of the session ID.

Returns
bool

Definition at line 147 of file Session.php.

◆ suggestLoginUsername()

MediaWiki\Session\Session::suggestLoginUsername ( )

Get a suggested username for the login form.

Returns
string|null

Definition at line 207 of file Session.php.

◆ unpersist()

MediaWiki\Session\Session::unpersist ( )

Make this session not be persisted across requests.

This will remove persistence information (e.g. delete cookies) from the associated WebRequest(s), and delete session data in the backend. The session data will still be available via get() until the end of the request.

Definition at line 138 of file Session.php.

◆ valid()

MediaWiki\Session\Session::valid ( )

@inheritDoc

Definition at line 661 of file Session.php.

References MediaWiki\Session\Session\key().

Member Data Documentation

◆ $backend

SessionBackend MediaWiki\Session\Session::$backend
private

Session backend.

Definition at line 53 of file Session.php.

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

◆ $encryptionAlgorithm

null string [] MediaWiki\Session\Session::$encryptionAlgorithm = null
staticprivate

Encryption algorithm to use.

Definition at line 50 of file Session.php.

Referenced by MediaWiki\Session\Session\getEncryptionAlgorithm().

◆ $index

int MediaWiki\Session\Session::$index
private

Session index.

Definition at line 56 of file Session.php.

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

◆ $logger

LoggerInterface MediaWiki\Session\Session::$logger
private

Definition at line 59 of file Session.php.

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


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