MediaWiki REL1_35
MediaWiki\Session\ImmutableSessionProviderWithCookie Class Reference

An ImmutableSessionProviderWithCookie doesn't persist the user, but optionally can use a cookie to support multiple IDs per session. More...

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

Public Member Functions

 __construct ( $params=[])
 Stable to call.
 
 canChangeUser ()
 Indicate whether the user associated with the request can be changed.If false, any session passed to self::persistSession() will have a user that was originally provided by self::provideSessionInfo(). Further, self::provideSessionInfo() may only provide sessions that have a user already set.If true, the provider may be passed sessions with arbitrary users, and will be expected to manipulate the request in such a way that future requests will cause self::provideSessionInfo() to provide a SessionInfo with that ID. This can be as simple as not passing any 'userInfo' into SessionInfo's constructor, in which case SessionInfo will load the user from the saved session's metadata.For example, a session provider for OAuth or SSL client certificates would function by matching the OAuth headers or certificate to a particular user, and thus would return false here since it can't arbitrarily assign those OAuth credentials or that certificate to a different user. A session provider that shoves information into cookies, on the other hand, could easily do so.
Note
For use by \MediaWiki\Session\SessionBackend only
Returns
bool
Stable to override
 
 getVaryCookies ()
 Return the list of cookies that need varying on.Stable to override

Note
For use by \MediaWiki\Session\SessionManager only
Returns
string[]
Stable to override
 
 persistSession (SessionBackend $session, WebRequest $request)
 Persist a session into a request/response.For example, you might set cookies for the session's ID, user ID, user name, and user token on the passed request.To correctly persist a user independently of the session ID, the provider should persist both the user ID (or name, but preferably the ID) and the user token. When reading the data from the request, it should construct a User object from the ID/name and then verify that the User object's token matches the token included in the request. Should the tokens not match, an anonymous user must be passed to SessionInfo::__construct().When persisting a user independently of the session ID, $session->shouldRememberUser() should be checked first. If this returns false, the user token must not be saved to cookies. The user name and/or ID may be persisted, and should be used to construct an unverified UserInfo to pass to SessionInfo::__construct().A backend that cannot persist sesison ID or user info should implement this as a no-op.
Note
For use by \MediaWiki\Session\SessionBackend only
Parameters
SessionBackend$sessionSession to persist
WebRequest$requestRequest into which to persist the session
Stable to override
 
 persistsSessionId ()
 Indicate whether self::persistSession() can save arbitrary session IDs.If false, any session passed to self::persistSession() will have an ID that was originally provided by self::provideSessionInfo().If true, the provider may be passed sessions with arbitrary session IDs, and will be expected to manipulate the request in such a way that future requests will cause self::provideSessionInfo() to provide a SessionInfo with that ID.For example, a session provider for OAuth would function by matching the OAuth headers to a particular user, and then would use self::hashToSessionId() to turn the user and OAuth client ID (and maybe also the user token and client secret) into a session ID, and therefore can't easily assign that user+client a different ID. Similarly, a session provider for SSL client certificates would function by matching the certificate to a particular user, and then would use self::hashToSessionId() to turn the user and certificate fingerprint into a session ID, and therefore can't easily assign a different ID either. On the other hand, a provider that saves the session ID into a cookie can easily just set the cookie to a different value.
Note
For use by \MediaWiki\Session\SessionBackend only
Returns
bool
Stable to override
 
 unpersistSession (WebRequest $request)
 Remove any persisted session from a request/response.For example, blank and expire any cookies set by self::persistSession().A backend that cannot persist sesison ID or user info should implement this as a no-op.
Note
For use by \MediaWiki\Session\SessionManager only
Parameters
WebRequest$requestRequest from which to remove any session data
Stable to override
 
 whyNoSession ()
 Return a Message for why sessions might not be being persisted.For example, "check whether you're blocking our cookies".
Returns
Message|null
Stable to override Stable to override
 
- Public Member Functions inherited from MediaWiki\Session\SessionProvider
 __construct ()
 Stable to call.
 
 __toString ()
 
 describe (Language $lang)
 Return an identifier for this session type.
Parameters
Language$langLanguage to use.
Returns
string
Stable to override
 
 getAllowedUserRights (SessionBackend $backend)
 Fetch the rights allowed the user when the specified session is active.
 
 getManager ()
 Get the session manager.
 
 getRememberUserDuration ()
 Returns the duration (in seconds) for which users will be remembered when Session::setRememberUser() is set.
 
 getVaryHeaders ()
 Return the HTTP headers that need varying on.
 
 invalidateSessionsForUser (User $user)
 Invalidate existing sessions for a user.
 
 mergeMetadata (array $savedMetadata, array $providedMetadata)
 Merge saved session provider metadata.
 
 newSessionInfo ( $id=null)
 Provide session info for a new, empty session.
 
 preventSessionsForUser ( $username)
 Prevent future sessions for the user.
 
 provideSessionInfo (WebRequest $request)
 Provide session info for a request.
 
 refreshSessionInfo (SessionInfo $info, WebRequest $request, &$metadata)
 Validate a loaded SessionInfo and refresh provider metadata.
 
 safeAgainstCsrf ()
 Most session providers require protection against CSRF attacks (usually via CSRF tokens)
 
 sessionIdWasReset (SessionBackend $session, $oldId)
 Notification that the session ID was reset.
 
 setConfig (Config $config)
 Set configuration.
 
 setHookContainer ( $hookContainer)
 Set the hook container.
 
 setLogger (LoggerInterface $logger)
 
 setManager (SessionManager $manager)
 Set the session manager.
 
 suggestLoginUsername (WebRequest $request)
 Get a suggested username for the login form Stable to override.
 

Protected Member Functions

 getSessionIdFromCookie (WebRequest $request)
 Get the session ID from the cookie, if any.
 
- Protected Member Functions inherited from MediaWiki\Session\SessionProvider
 describeMessage ()
 Return a Message identifying this session type.
 
 getHookContainer ()
 Get the HookContainer.
 
 getHookRunner ()
 Get the HookRunner.
 
 hashToSessionId ( $data, $key=null)
 Hash data as a session ID.
 

Protected Attributes

string null $sessionCookieName = null
 
mixed[] $sessionCookieOptions = []
 
- Protected Attributes inherited from MediaWiki\Session\SessionProvider
Config $config
 
LoggerInterface $logger
 
SessionManager $manager
 
int $priority
 Session priority.
 

Detailed Description

An ImmutableSessionProviderWithCookie doesn't persist the user, but optionally can use a cookie to support multiple IDs per session.

As mentioned in the documentation for SessionProvider, many methods that are technically "cannot persist ID" could be turned into "can persist ID but not changing User" using a session cookie. This class implements such an optional session cookie.

Stable to extend

Since
1.27

Definition at line 41 of file ImmutableSessionProviderWithCookie.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Session\ImmutableSessionProviderWithCookie::__construct (   $params = [])

Stable to call.

Parameters
array$paramsKeys include:
  • sessionCookieName: Session cookie name, if multiple sessions per client are to be supported.
  • sessionCookieOptions: Options to pass to WebResponse::setCookie().

Definition at line 55 of file ImmutableSessionProviderWithCookie.php.

Member Function Documentation

◆ canChangeUser()

MediaWiki\Session\ImmutableSessionProviderWithCookie::canChangeUser ( )

Indicate whether the user associated with the request can be changed.If false, any session passed to self::persistSession() will have a user that was originally provided by self::provideSessionInfo(). Further, self::provideSessionInfo() may only provide sessions that have a user already set.If true, the provider may be passed sessions with arbitrary users, and will be expected to manipulate the request in such a way that future requests will cause self::provideSessionInfo() to provide a SessionInfo with that ID. This can be as simple as not passing any 'userInfo' into SessionInfo's constructor, in which case SessionInfo will load the user from the saved session's metadata.For example, a session provider for OAuth or SSL client certificates would function by matching the OAuth headers or certificate to a particular user, and thus would return false here since it can't arbitrarily assign those OAuth credentials or that certificate to a different user. A session provider that shoves information into cookies, on the other hand, could easily do so.

Note
For use by \MediaWiki\Session\SessionBackend only
Returns
bool
Stable to override

Reimplemented from MediaWiki\Session\SessionProvider.

Definition at line 107 of file ImmutableSessionProviderWithCookie.php.

◆ getSessionIdFromCookie()

MediaWiki\Session\ImmutableSessionProviderWithCookie::getSessionIdFromCookie ( WebRequest  $request)
protected

Get the session ID from the cookie, if any.

Only call this if $this->sessionCookieName !== null. If sessionCookieName is null, do some logic (probably involving a call to $this->hashToSessionId()) to create the single session ID corresponding to this WebRequest instead of calling this method.

Parameters
WebRequest$request
Returns
string|null

Definition at line 83 of file ImmutableSessionProviderWithCookie.php.

References WebRequest\getCookie(), and MediaWiki\Session\SessionManager\validateSessionId().

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

◆ getVaryCookies()

MediaWiki\Session\ImmutableSessionProviderWithCookie::getVaryCookies ( )

Return the list of cookies that need varying on.Stable to override

Note
For use by \MediaWiki\Session\SessionManager only
Returns
string[]
Stable to override

Reimplemented from MediaWiki\Session\SessionProvider.

Definition at line 163 of file ImmutableSessionProviderWithCookie.php.

References MediaWiki\Session\ImmutableSessionProviderWithCookie\$sessionCookieName.

◆ persistSession()

MediaWiki\Session\ImmutableSessionProviderWithCookie::persistSession ( SessionBackend  $session,
WebRequest  $request 
)

Persist a session into a request/response.For example, you might set cookies for the session's ID, user ID, user name, and user token on the passed request.To correctly persist a user independently of the session ID, the provider should persist both the user ID (or name, but preferably the ID) and the user token. When reading the data from the request, it should construct a User object from the ID/name and then verify that the User object's token matches the token included in the request. Should the tokens not match, an anonymous user must be passed to SessionInfo::__construct().When persisting a user independently of the session ID, $session->shouldRememberUser() should be checked first. If this returns false, the user token must not be saved to cookies. The user name and/or ID may be persisted, and should be used to construct an unverified UserInfo to pass to SessionInfo::__construct().A backend that cannot persist sesison ID or user info should implement this as a no-op.

Note
For use by \MediaWiki\Session\SessionBackend only
Parameters
SessionBackend$sessionSession to persist
WebRequest$requestRequest into which to persist the session
Stable to override

Reimplemented from MediaWiki\Session\SessionProvider.

Definition at line 115 of file ImmutableSessionProviderWithCookie.php.

References MediaWiki\Session\ImmutableSessionProviderWithCookie\$sessionCookieOptions, MediaWiki\Session\SessionBackend\getId(), MediaWiki\Session\SessionBackend\getUser(), WebRequest\response(), and MediaWiki\Session\SessionBackend\shouldForceHTTPS().

◆ persistsSessionId()

MediaWiki\Session\ImmutableSessionProviderWithCookie::persistsSessionId ( )

Indicate whether self::persistSession() can save arbitrary session IDs.If false, any session passed to self::persistSession() will have an ID that was originally provided by self::provideSessionInfo().If true, the provider may be passed sessions with arbitrary session IDs, and will be expected to manipulate the request in such a way that future requests will cause self::provideSessionInfo() to provide a SessionInfo with that ID.For example, a session provider for OAuth would function by matching the OAuth headers to a particular user, and then would use self::hashToSessionId() to turn the user and OAuth client ID (and maybe also the user token and client secret) into a session ID, and therefore can't easily assign that user+client a different ID. Similarly, a session provider for SSL client certificates would function by matching the certificate to a particular user, and then would use self::hashToSessionId() to turn the user and certificate fingerprint into a session ID, and therefore can't easily assign a different ID either. On the other hand, a provider that saves the session ID into a cookie can easily just set the cookie to a different value.

Note
For use by \MediaWiki\Session\SessionBackend only
Returns
bool
Stable to override

Reimplemented from MediaWiki\Session\SessionProvider.

Definition at line 99 of file ImmutableSessionProviderWithCookie.php.

◆ unpersistSession()

MediaWiki\Session\ImmutableSessionProviderWithCookie::unpersistSession ( WebRequest  $request)

Remove any persisted session from a request/response.For example, blank and expire any cookies set by self::persistSession().A backend that cannot persist sesison ID or user info should implement this as a no-op.

Note
For use by \MediaWiki\Session\SessionManager only
Parameters
WebRequest$requestRequest from which to remove any session data
Stable to override

Reimplemented from MediaWiki\Session\SessionProvider.

Definition at line 144 of file ImmutableSessionProviderWithCookie.php.

References WebRequest\response().

◆ whyNoSession()

MediaWiki\Session\ImmutableSessionProviderWithCookie::whyNoSession ( )

Return a Message for why sessions might not be being persisted.For example, "check whether you're blocking our cookies".

Returns
Message|null
Stable to override Stable to override

Reimplemented from MediaWiki\Session\SessionProvider.

Definition at line 172 of file ImmutableSessionProviderWithCookie.php.

References wfMessage().

Member Data Documentation

◆ $sessionCookieName

string null MediaWiki\Session\ImmutableSessionProviderWithCookie::$sessionCookieName = null
protected

◆ $sessionCookieOptions

mixed [] MediaWiki\Session\ImmutableSessionProviderWithCookie::$sessionCookieOptions = []
protected

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