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 * Indicate whether the session user info can be changed
319 public function canSetUser() {
320 return $this->provider
->canChangeUser();
324 * Set a new user for this session
325 * @note This should only be called when the user has been authenticated via a login process
326 * @param User $user User to set on the session.
327 * This may become a "UserValue" in the future, or User may be refactored
330 public function setUser( $user ) {
331 if ( !$this->canSetUser() ) {
332 throw new \
BadMethodCallException(
333 'Cannot set user on this session; check $session->canSetUser() first'
338 $this->metaDirty
= true;
339 $this->logger
->debug( "SessionBackend $this->id metadata dirty due to user change" );
344 * Get a suggested username for the login form
345 * @param int $index Session index
346 * @return string|null
348 public function suggestLoginUsername( $index ) {
349 if ( !isset( $this->requests
[$index] ) ) {
350 throw new \
InvalidArgumentException( 'Invalid session index' );
352 return $this->provider
->suggestLoginUsername( $this->requests
[$index] );
356 * Whether HTTPS should be forced
359 public function shouldForceHTTPS() {
360 return $this->forceHTTPS
;
364 * Set whether HTTPS should be forced
367 public function setForceHTTPS( $force ) {
368 if ( $this->forceHTTPS
!== (bool)$force ) {
369 $this->forceHTTPS
= (bool)$force;
370 $this->metaDirty
= true;
371 $this->logger
->debug( "SessionBackend $this->id metadata dirty due to force-HTTPS change" );
377 * Fetch the "logged out" timestamp
380 public function getLoggedOutTimestamp() {
381 return $this->loggedOut
;
385 * Set the "logged out" timestamp
388 public function setLoggedOutTimestamp( $ts = null ) {
390 if ( $this->loggedOut
!== $ts ) {
391 $this->loggedOut
= $ts;
392 $this->metaDirty
= true;
393 $this->logger
->debug(
394 "SessionBackend $this->id metadata dirty due to logged-out-timestamp change"
401 * Fetch provider metadata
402 * @protected For use by SessionProvider subclasses only
405 public function getProviderMetadata() {
406 return $this->providerMetadata
;
410 * Fetch the session data array
412 * Note the caller is responsible for calling $this->dirty() if anything in
413 * the array is changed.
415 * @private For use by \\MediaWiki\\Session\\Session only.
418 public function &getData() {
423 * Add data to the session.
425 * Overwrites any existing data under the same keys.
427 * @param array $newData Key-value pairs to add to the session
429 public function addData( array $newData ) {
430 $data = &$this->getData();
431 foreach ( $newData as $key => $value ) {
432 if ( !array_key_exists( $key, $data ) ||
$data[$key] !== $value ) {
433 $data[$key] = $value;
434 $this->dataDirty
= true;
435 $this->logger
->debug(
436 "SessionBackend $this->id data dirty due to addData(): " . wfGetAllCallers( 5 )
444 * @private For use by \\MediaWiki\\Session\\Session only.
446 public function dirty() {
447 $this->dataDirty
= true;
448 $this->logger
->debug(
449 "SessionBackend $this->id data dirty due to dirty(): " . wfGetAllCallers( 5 )
454 * Renew the session by resaving everything
456 * Resets the TTL in the backend store if the session is near expiring, and
457 * re-persists the session to any active WebRequests if persistent.
459 public function renew() {
460 if ( time() +
$this->lifetime
/ 2 > $this->expires
) {
461 $this->metaDirty
= true;
462 $this->logger
->debug(
463 "SessionBackend $this->id metadata dirty for renew(): " . wfGetAllCallers( 5 )
465 if ( $this->persist
) {
466 $this->forcePersist
= true;
467 $this->logger
->debug(
468 "SessionBackend $this->id force-persist for renew(): " . wfGetAllCallers( 5 )
476 * Delay automatic saving while multiple updates are being made
478 * Calls to save() will not be delayed.
480 * @return \ScopedCallback When this goes out of scope, a save will be triggered
482 public function delaySave() {
485 $ref = &$this->delaySave
;
486 return new \
ScopedCallback( function () use ( $that, &$ref ) {
495 * Save and persist session data, unless delayed
497 private function autosave() {
498 if ( $this->delaySave
<= 0 ) {
504 * Save and persist session data
505 * @param bool $closing Whether the session is being closed
507 public function save( $closing = false ) {
508 if ( $this->provider
->getManager()->isUserSessionPrevented( $this->user
->getName() ) ) {
509 $this->logger
->debug(
510 "SessionBackend $this->id not saving, " .
511 "user {$this->user} was passed to SessionManager::preventSessionsForUser"
516 // Ensure the user has a token
517 // @codeCoverageIgnoreStart
518 $anon = $this->user
->isAnon();
519 if ( !$anon && !$this->user
->getToken() ) {
520 $this->logger
->debug(
521 "SessionBackend $this->id creating token for user {$this->user} on save"
523 $this->user
->setToken();
524 if ( !wfReadOnly() ) {
525 $this->user
->saveSettings();
527 $this->metaDirty
= true;
529 // @codeCoverageIgnoreEnd
531 if ( !$this->metaDirty
&& !$this->dataDirty
&&
532 $this->dataHash
!== md5( serialize( $this->data
) )
534 $this->logger
->debug( "SessionBackend $this->id data dirty due to hash mismatch, " .
535 "$this->dataHash !== " . md5( serialize( $this->data
) ) );
536 $this->dataDirty
= true;
539 if ( !$this->metaDirty
&& !$this->dataDirty
&& !$this->forcePersist
) {
543 $this->logger
->debug( "SessionBackend $this->id save: " .
544 'dataDirty=' . (int)$this->dataDirty
. ' ' .
545 'metaDirty=' . (int)$this->metaDirty
. ' ' .
546 'forcePersist=' . (int)$this->forcePersist
549 // Persist to the provider, if flagged
550 if ( $this->persist
&& ( $this->metaDirty ||
$this->forcePersist
) ) {
551 foreach ( $this->requests
as $request ) {
552 $request->setSessionId( $this->getSessionId() );
553 $this->provider
->persistSession( $this, $request );
556 $this->checkPHPSession();
560 $this->forcePersist
= false;
562 if ( !$this->metaDirty
&& !$this->dataDirty
) {
566 // Save session data to store, if necessary
567 $metadata = $origMetadata = array(
568 'provider' => (string)$this->provider
,
569 'providerMetadata' => $this->providerMetadata
,
570 'userId' => $anon ?
0 : $this->user
->getId(),
571 'userName' => $anon ?
null : $this->user
->getName(),
572 'userToken' => $anon ?
null : $this->user
->getToken(),
573 'remember' => !$anon && $this->remember
,
574 'forceHTTPS' => $this->forceHTTPS
,
575 'expires' => time() +
$this->lifetime
,
576 'loggedOut' => $this->loggedOut
,
579 \Hooks
::run( 'SessionMetadata', array( $this, &$metadata, $this->requests
) );
581 foreach ( $origMetadata as $k => $v ) {
582 if ( $metadata[$k] !== $v ) {
583 throw new \
UnexpectedValueException( "SessionMetadata hook changed metadata key \"$k\"" );
588 wfMemcKey( 'MWSession', (string)$this->id
),
590 'data' => $this->data
,
591 'metadata' => $metadata,
596 $this->metaDirty
= false;
597 $this->dataDirty
= false;
598 $this->dataHash
= md5( serialize( $this->data
) );
599 $this->expires
= $metadata['expires'];
603 * For backwards compatibility, open the PHP session when the global
604 * session is persisted
606 private function checkPHPSession() {
607 if ( !$this->checkPHPSessionRecursionGuard
) {
608 $this->checkPHPSessionRecursionGuard
= true;
609 $ref = &$this->checkPHPSessionRecursionGuard
;
610 $reset = new \
ScopedCallback( function () use ( &$ref ) {
614 if ( $this->usePhpSessionHandling
&& session_id() === '' && PHPSessionHandler
::isEnabled() &&
615 SessionManager
::getGlobalSession()->getId() === (string)$this->id
617 $this->logger
->debug( "SessionBackend $this->id: Taking over PHP session" );
618 session_id( (string)$this->id
);
619 \MediaWiki\
quietCall( 'session_start' );