3 * MediaWiki session backend
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
24 namespace MediaWiki\Session
;
27 use Psr\Log\LoggerInterface
;
32 * This is the actual workhorse for Session.
34 * Most code does not need to use this class, you want \\MediaWiki\\Session\\Session.
35 * The exceptions are SessionProviders and SessionMetadata hook functions,
36 * which get an instance of this class rather than Session.
38 * The reasons for this split are:
39 * 1. A session can be attached to multiple requests, but we want the Session
40 * object to have some features that correspond to just one of those
42 * 2. We want reasonable garbage collection behavior, but we also want the
43 * SessionManager to hold a reference to every active session so it can be
44 * saved when the request ends.
49 final class SessionBackend
{
53 private $persist = false;
54 private $remember = false;
55 private $forceHTTPS = false;
57 /** @var array|null */
60 private $forcePersist = false;
61 private $metaDirty = false;
62 private $dataDirty = false;
64 /** @var string Used to detect subarray modifications */
65 private $dataHash = null;
70 /** @var LoggerInterface */
79 private $curIndex = 0;
81 /** @var WebRequest[] Session requests */
82 private $requests = array();
84 /** @var SessionProvider provider */
87 /** @var array|null provider-specified metadata */
88 private $providerMetadata = null;
91 private $loggedOut = 0;
92 private $delaySave = 0;
94 private $usePhpSessionHandling = true;
95 private $checkPHPSessionRecursionGuard = false;
98 * @param SessionId $id Session ID object
99 * @param SessionInfo $info Session info to populate from
100 * @param BagOStuff $store Backend data store
101 * @param LoggerInterface $logger
102 * @param int $lifetime Session data lifetime in seconds
104 public function __construct(
105 SessionId
$id, SessionInfo
$info, BagOStuff
$store, LoggerInterface
$logger, $lifetime
107 $phpSessionHandling = \RequestContext
::getMain()->getConfig()->get( 'PHPSessionHandling' );
108 $this->usePhpSessionHandling
= $phpSessionHandling !== 'disable';
110 if ( $info->getUserInfo() && !$info->getUserInfo()->isVerified() ) {
111 throw new \
InvalidArgumentException(
112 "Refusing to create session for unverified user {$info->getUserInfo()}"
115 if ( $info->getProvider() === null ) {
116 throw new \
InvalidArgumentException( 'Cannot create session without a provider' );
118 if ( $info->getId() !== $id->getId() ) {
119 throw new \
InvalidArgumentException( 'SessionId and SessionInfo don\'t match' );
123 $this->user
= $info->getUserInfo() ?
$info->getUserInfo()->getUser() : new User
;
124 $this->store
= $store;
125 $this->logger
= $logger;
126 $this->lifetime
= $lifetime;
127 $this->provider
= $info->getProvider();
128 $this->persist
= $info->wasPersisted();
129 $this->remember
= $info->wasRemembered();
130 $this->forceHTTPS
= $info->forceHTTPS();
131 $this->providerMetadata
= $info->getProviderMetadata();
133 $blob = $store->get( wfMemcKey( 'MWSession', (string)$this->id
) );
134 if ( !is_array( $blob ) ||
135 !isset( $blob['metadata'] ) ||
!is_array( $blob['metadata'] ) ||
136 !isset( $blob['data'] ) ||
!is_array( $blob['data'] )
138 $this->data
= array();
139 $this->dataDirty
= true;
140 $this->metaDirty
= true;
141 $this->logger
->debug( "SessionBackend $this->id is unsaved, marking dirty in constructor" );
143 $this->data
= $blob['data'];
144 if ( isset( $blob['metadata']['loggedOut'] ) ) {
145 $this->loggedOut
= (int)$blob['metadata']['loggedOut'];
147 if ( isset( $blob['metadata']['expires'] ) ) {
148 $this->expires
= (int)$blob['metadata']['expires'];
150 $this->metaDirty
= true;
151 $this->logger
->debug(
152 "SessionBackend $this->id metadata dirty due to missing expiration timestamp"
156 $this->dataHash
= md5( serialize( $this->data
) );
160 * Return a new Session for this backend
161 * @param WebRequest $request
164 public function getSession( WebRequest
$request ) {
165 $index = ++
$this->curIndex
;
166 $this->requests
[$index] = $request;
167 $session = new Session( $this, $index );
172 * Deregister a Session
173 * @private For use by \\MediaWiki\\Session\\Session::__destruct() only
176 public function deregisterSession( $index ) {
177 unset( $this->requests
[$index] );
178 if ( !count( $this->requests
) ) {
180 $this->provider
->getManager()->deregisterSessionBackend( $this );
185 * Returns the session ID.
188 public function getId() {
189 return (string)$this->id
;
193 * Fetch the SessionId object
194 * @private For internal use by WebRequest
197 public function getSessionId() {
202 * Changes the session ID
203 * @return string New ID (might be the same as the old)
205 public function resetId() {
206 if ( $this->provider
->persistsSessionId() ) {
207 $oldId = (string)$this->id
;
208 $restart = $this->usePhpSessionHandling
&& $oldId === session_id() &&
209 PHPSessionHandler
::isEnabled();
212 // If this session is the one behind PHP's $_SESSION, we need
213 // to close then reopen it.
214 session_write_close();
217 $this->provider
->getManager()->changeBackendId( $this );
218 $this->provider
->sessionIdWasReset( $this, $oldId );
219 $this->metaDirty
= true;
220 $this->logger
->debug(
221 "SessionBackend $this->id metadata dirty due to ID reset (formerly $oldId)"
225 session_id( (string)$this->id
);
226 \MediaWiki\
quietCall( 'session_start' );
231 // Delete the data for the old session ID now
232 $this->store
->delete( wfMemcKey( 'MWSession', $oldId ) );
237 * Fetch the SessionProvider for this session
238 * @return SessionProviderInterface
240 public function getProvider() {
241 return $this->provider
;
245 * Indicate whether this session is persisted across requests
247 * For example, if cookies are set.
251 public function isPersistent() {
252 return $this->persist
;
256 * Make this session persisted across requests
258 * If the session is already persistent, equivalent to calling
261 public function persist() {
262 if ( !$this->persist
) {
263 $this->persist
= true;
264 $this->forcePersist
= true;
265 $this->logger
->debug( "SessionBackend $this->id force-persist due to persist()" );
273 * Indicate whether the user should be remembered independently of the
277 public function shouldRememberUser() {
278 return $this->remember
;
282 * Set whether the user should be remembered independently of the session
284 * @param bool $remember
286 public function setRememberUser( $remember ) {
287 if ( $this->remember
!== (bool)$remember ) {
288 $this->remember
= (bool)$remember;
289 $this->metaDirty
= true;
290 $this->logger
->debug( "SessionBackend $this->id metadata dirty due to remember-user change" );
296 * Returns the request associated with a Session
297 * @param int $index Session index
300 public function getRequest( $index ) {
301 if ( !isset( $this->requests
[$index] ) ) {
302 throw new \
InvalidArgumentException( 'Invalid session index' );
304 return $this->requests
[$index];
308 * Returns the authenticated user for this session
311 public function getUser() {
316 * Fetch the rights allowed the user when this session is active.
317 * @return null|string[] Allowed user rights, or null to allow all.
319 public function getAllowedUserRights() {
320 return $this->provider
->getAllowedUserRights( $this );
324 * Indicate whether the session user info can be changed
327 public function canSetUser() {
328 return $this->provider
->canChangeUser();
332 * Set a new user for this session
333 * @note This should only be called when the user has been authenticated via a login process
334 * @param User $user User to set on the session.
335 * This may become a "UserValue" in the future, or User may be refactored
338 public function setUser( $user ) {
339 if ( !$this->canSetUser() ) {
340 throw new \
BadMethodCallException(
341 'Cannot set user on this session; check $session->canSetUser() first'
346 $this->metaDirty
= true;
347 $this->logger
->debug( "SessionBackend $this->id metadata dirty due to user change" );
352 * Get a suggested username for the login form
353 * @param int $index Session index
354 * @return string|null
356 public function suggestLoginUsername( $index ) {
357 if ( !isset( $this->requests
[$index] ) ) {
358 throw new \
InvalidArgumentException( 'Invalid session index' );
360 return $this->provider
->suggestLoginUsername( $this->requests
[$index] );
364 * Whether HTTPS should be forced
367 public function shouldForceHTTPS() {
368 return $this->forceHTTPS
;
372 * Set whether HTTPS should be forced
375 public function setForceHTTPS( $force ) {
376 if ( $this->forceHTTPS
!== (bool)$force ) {
377 $this->forceHTTPS
= (bool)$force;
378 $this->metaDirty
= true;
379 $this->logger
->debug( "SessionBackend $this->id metadata dirty due to force-HTTPS change" );
385 * Fetch the "logged out" timestamp
388 public function getLoggedOutTimestamp() {
389 return $this->loggedOut
;
393 * Set the "logged out" timestamp
396 public function setLoggedOutTimestamp( $ts = null ) {
398 if ( $this->loggedOut
!== $ts ) {
399 $this->loggedOut
= $ts;
400 $this->metaDirty
= true;
401 $this->logger
->debug(
402 "SessionBackend $this->id metadata dirty due to logged-out-timestamp change"
409 * Fetch provider metadata
410 * @protected For use by SessionProvider subclasses only
413 public function getProviderMetadata() {
414 return $this->providerMetadata
;
418 * Fetch the session data array
420 * Note the caller is responsible for calling $this->dirty() if anything in
421 * the array is changed.
423 * @private For use by \\MediaWiki\\Session\\Session only.
426 public function &getData() {
431 * Add data to the session.
433 * Overwrites any existing data under the same keys.
435 * @param array $newData Key-value pairs to add to the session
437 public function addData( array $newData ) {
438 $data = &$this->getData();
439 foreach ( $newData as $key => $value ) {
440 if ( !array_key_exists( $key, $data ) ||
$data[$key] !== $value ) {
441 $data[$key] = $value;
442 $this->dataDirty
= true;
443 $this->logger
->debug(
444 "SessionBackend $this->id data dirty due to addData(): " . wfGetAllCallers( 5 )
452 * @private For use by \\MediaWiki\\Session\\Session only.
454 public function dirty() {
455 $this->dataDirty
= true;
456 $this->logger
->debug(
457 "SessionBackend $this->id data dirty due to dirty(): " . wfGetAllCallers( 5 )
462 * Renew the session by resaving everything
464 * Resets the TTL in the backend store if the session is near expiring, and
465 * re-persists the session to any active WebRequests if persistent.
467 public function renew() {
468 if ( time() +
$this->lifetime
/ 2 > $this->expires
) {
469 $this->metaDirty
= true;
470 $this->logger
->debug(
471 "SessionBackend $this->id metadata dirty for renew(): " . wfGetAllCallers( 5 )
473 if ( $this->persist
) {
474 $this->forcePersist
= true;
475 $this->logger
->debug(
476 "SessionBackend $this->id force-persist for renew(): " . wfGetAllCallers( 5 )
484 * Delay automatic saving while multiple updates are being made
486 * Calls to save() will not be delayed.
488 * @return \ScopedCallback When this goes out of scope, a save will be triggered
490 public function delaySave() {
493 $ref = &$this->delaySave
;
494 return new \
ScopedCallback( function () use ( $that, &$ref ) {
503 * Save and persist session data, unless delayed
505 private function autosave() {
506 if ( $this->delaySave
<= 0 ) {
512 * Save and persist session data
513 * @param bool $closing Whether the session is being closed
515 public function save( $closing = false ) {
516 if ( $this->provider
->getManager()->isUserSessionPrevented( $this->user
->getName() ) ) {
517 $this->logger
->debug(
518 "SessionBackend $this->id not saving, " .
519 "user {$this->user} was passed to SessionManager::preventSessionsForUser"
524 // Ensure the user has a token
525 // @codeCoverageIgnoreStart
526 $anon = $this->user
->isAnon();
527 if ( !$anon && !$this->user
->getToken() ) {
528 $this->logger
->debug(
529 "SessionBackend $this->id creating token for user {$this->user} on save"
531 $this->user
->setToken();
532 if ( !wfReadOnly() ) {
533 $this->user
->saveSettings();
535 $this->metaDirty
= true;
537 // @codeCoverageIgnoreEnd
539 if ( !$this->metaDirty
&& !$this->dataDirty
&&
540 $this->dataHash
!== md5( serialize( $this->data
) )
542 $this->logger
->debug( "SessionBackend $this->id data dirty due to hash mismatch, " .
543 "$this->dataHash !== " . md5( serialize( $this->data
) ) );
544 $this->dataDirty
= true;
547 if ( !$this->metaDirty
&& !$this->dataDirty
&& !$this->forcePersist
) {
551 $this->logger
->debug( "SessionBackend $this->id save: " .
552 'dataDirty=' . (int)$this->dataDirty
. ' ' .
553 'metaDirty=' . (int)$this->metaDirty
. ' ' .
554 'forcePersist=' . (int)$this->forcePersist
557 // Persist to the provider, if flagged
558 if ( $this->persist
&& ( $this->metaDirty ||
$this->forcePersist
) ) {
559 foreach ( $this->requests
as $request ) {
560 $request->setSessionId( $this->getSessionId() );
561 $this->provider
->persistSession( $this, $request );
564 $this->checkPHPSession();
568 $this->forcePersist
= false;
570 if ( !$this->metaDirty
&& !$this->dataDirty
) {
574 // Save session data to store, if necessary
575 $metadata = $origMetadata = array(
576 'provider' => (string)$this->provider
,
577 'providerMetadata' => $this->providerMetadata
,
578 'userId' => $anon ?
0 : $this->user
->getId(),
579 'userName' => $anon ?
null : $this->user
->getName(),
580 'userToken' => $anon ?
null : $this->user
->getToken(),
581 'remember' => !$anon && $this->remember
,
582 'forceHTTPS' => $this->forceHTTPS
,
583 'expires' => time() +
$this->lifetime
,
584 'loggedOut' => $this->loggedOut
,
587 \Hooks
::run( 'SessionMetadata', array( $this, &$metadata, $this->requests
) );
589 foreach ( $origMetadata as $k => $v ) {
590 if ( $metadata[$k] !== $v ) {
591 throw new \
UnexpectedValueException( "SessionMetadata hook changed metadata key \"$k\"" );
596 wfMemcKey( 'MWSession', (string)$this->id
),
598 'data' => $this->data
,
599 'metadata' => $metadata,
604 $this->metaDirty
= false;
605 $this->dataDirty
= false;
606 $this->dataHash
= md5( serialize( $this->data
) );
607 $this->expires
= $metadata['expires'];
611 * For backwards compatibility, open the PHP session when the global
612 * session is persisted
614 private function checkPHPSession() {
615 if ( !$this->checkPHPSessionRecursionGuard
) {
616 $this->checkPHPSessionRecursionGuard
= true;
617 $ref = &$this->checkPHPSessionRecursionGuard
;
618 $reset = new \
ScopedCallback( function () use ( &$ref ) {
622 if ( $this->usePhpSessionHandling
&& session_id() === '' && PHPSessionHandler
::isEnabled() &&
623 SessionManager
::getGlobalSession()->getId() === (string)$this->id
625 $this->logger
->debug( "SessionBackend $this->id: Taking over PHP session" );
626 session_id( (string)$this->id
);
627 \MediaWiki\
quietCall( 'session_start' );