includes/session/Session.php

   1 <?php
   2 /**
   3  * MediaWiki session
   4  *
   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.
   9  *
  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.
  14  *
  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
  19  *
  20  * @file
  21  * @ingroup Session
  22  */
  23
  24 namespace MediaWiki\Session;
  25
  26 use User;
  27 use WebRequest;
  28
  29 /**
  30  * Manages data for an an authenticated session
  31  *
  32  * A Session represents the fact that the current HTTP request is part of a
  33  * session. There are two broad types of Sessions, based on whether they
  34  * return true or false from self::canSetUser():
  35  * * When true (mutable), the Session identifies multiple requests as part of
  36  *   a session generically, with no tie to a particular user.
  37  * * When false (immutable), the Session identifies multiple requests as part
  38  *   of a session by identifying and authenticating the request itself as
  39  *   belonging to a particular user.
  40  *
  41  * The Session object also serves as a replacement for PHP's $_SESSION,
  42  * managing access to per-session data.
  43  *
  44  * @todo Once we drop support for PHP 5.3.3, implementing ArrayAccess would be nice.
  45  * @ingroup Session
  46  * @since 1.27
  47  */
  48 final class Session implements \Countable, \Iterator {
  49         /** @var SessionBackend Session backend */
  50         private $backend;
  51
  52         /** @var int Session index */
  53         private $index;
  54
  55         /**
  56          * @param SessionBackend $backend
  57          * @param int $index
  58          */
  59         public function __construct( SessionBackend $backend, $index ) {
  60                 $this->backend = $backend;
  61                 $this->index = $index;
  62         }
  63
  64         public function __destruct() {
  65                 $this->backend->deregisterSession( $this->index );
  66         }
  67
  68         /**
  69          * Returns the session ID
  70          * @return string
  71          */
  72         public function getId() {
  73                 return $this->backend->getId();
  74         }
  75
  76         /**
  77          * Returns the SessionId object
  78          * @private For internal use by WebRequest
  79          * @return SessionId
  80          */
  81         public function getSessionId() {
  82                 return $this->backend->getSessionId();
  83         }
  84
  85         /**
  86          * Changes the session ID
  87          * @return string New ID (might be the same as the old)
  88          */
  89         public function resetId() {
  90                 return $this->backend->resetId();
  91         }
  92
  93         /**
  94          * Fetch the SessionProvider for this session
  95          * @return SessionProviderInterface
  96          */
  97         public function getProvider() {
  98                 return $this->backend->getProvider();
  99         }
 100
 101         /**
 102          * Indicate whether this session is persisted across requests
 103          *
 104          * For example, if cookies are set.
 105          *
 106          * @return bool
 107          */
 108         public function isPersistent() {
 109                 return $this->backend->isPersistent();
 110         }
 111
 112         /**
 113          * Make this session persisted across requests
 114          *
 115          * If the session is already persistent, equivalent to calling
 116          * $this->renew().
 117          */
 118         public function persist() {
 119                 $this->backend->persist();
 120         }
 121
 122         /**
 123          * Indicate whether the user should be remembered independently of the
 124          * session ID.
 125          * @return bool
 126          */
 127         public function shouldRememberUser() {
 128                 return $this->backend->shouldRememberUser();
 129         }
 130
 131         /**
 132          * Set whether the user should be remembered independently of the session
 133          * ID.
 134          * @param bool $remember
 135          */
 136         public function setRememberUser( $remember ) {
 137                 $this->backend->setRememberUser( $remember );
 138         }
 139
 140         /**
 141          * Returns the request associated with this session
 142          * @return WebRequest
 143          */
 144         public function getRequest() {
 145                 return $this->backend->getRequest( $this->index );
 146         }
 147
 148         /**
 149          * Returns the authenticated user for this session
 150          * @return User
 151          */
 152         public function getUser() {
 153                 return $this->backend->getUser();
 154         }
 155
 156         /**
 157          * Fetch the rights allowed the user when this session is active.
 158          * @return null|string[] Allowed user rights, or null to allow all.
 159          */
 160         public function getAllowedUserRights() {
 161                 return $this->backend->getAllowedUserRights();
 162         }
 163
 164         /**
 165          * Indicate whether the session user info can be changed
 166          * @return bool
 167          */
 168         public function canSetUser() {
 169                 return $this->backend->canSetUser();
 170         }
 171
 172         /**
 173          * Set a new user for this session
 174          * @note This should only be called when the user has been authenticated
 175          * @param User $user User to set on the session.
 176          *   This may become a "UserValue" in the future, or User may be refactored
 177          *   into such.
 178          */
 179         public function setUser( $user ) {
 180                 $this->backend->setUser( $user );
 181         }
 182
 183         /**
 184          * Get a suggested username for the login form
 185          * @return string|null
 186          */
 187         public function suggestLoginUsername() {
 188                 return $this->backend->suggestLoginUsername( $this->index );
 189         }
 190
 191         /**
 192          * Whether HTTPS should be forced
 193          * @return bool
 194          */
 195         public function shouldForceHTTPS() {
 196                 return $this->backend->shouldForceHTTPS();
 197         }
 198
 199         /**
 200          * Set whether HTTPS should be forced
 201          * @param bool $force
 202          */
 203         public function setForceHTTPS( $force ) {
 204                 $this->backend->setForceHTTPS( $force );
 205         }
 206
 207         /**
 208          * Fetch the "logged out" timestamp
 209          * @return int
 210          */
 211         public function getLoggedOutTimestamp() {
 212                 return $this->backend->getLoggedOutTimestamp();
 213         }
 214
 215         /**
 216          * Set the "logged out" timestamp
 217          * @param int $ts
 218          */
 219         public function setLoggedOutTimestamp( $ts ) {
 220                 $this->backend->setLoggedOutTimestamp( $ts );
 221         }
 222
 223         /**
 224          * Fetch provider metadata
 225          * @protected For use by SessionProvider subclasses only
 226          * @return mixed
 227          */
 228         public function getProviderMetadata() {
 229                 return $this->backend->getProviderMetadata();
 230         }
 231
 232         /**
 233          * Delete all session data and clear the user (if possible)
 234          */
 235         public function clear() {
 236                 $data = &$this->backend->getData();
 237                 if ( $data ) {
 238                         $data = array();
 239                         $this->backend->dirty();
 240                 }
 241                 if ( $this->backend->canSetUser() ) {
 242                         $this->backend->setUser( new User );
 243                 }
 244                 $this->backend->save();
 245         }
 246
 247         /**
 248          * Renew the session
 249          *
 250          * Resets the TTL in the backend store if the session is near expiring, and
 251          * re-persists the session to any active WebRequests if persistent.
 252          */
 253         public function renew() {
 254                 $this->backend->renew();
 255         }
 256
 257         /**
 258          * Fetch a copy of this session attached to an alternative WebRequest
 259          *
 260          * Actions on the copy will affect this session too, and vice versa.
 261          *
 262          * @param WebRequest $request Any existing session associated with this
 263          *  WebRequest object will be overwritten.
 264          * @return Session
 265          */
 266         public function sessionWithRequest( WebRequest $request ) {
 267                 $request->setSessionId( $this->backend->getSessionId() );
 268                 return $this->backend->getSession( $request );
 269         }
 270
 271         /**
 272          * Fetch a value from the session
 273          * @param string|int $key
 274          * @param mixed $default
 275          * @return mixed
 276          */
 277         public function get( $key, $default = null ) {
 278                 $data = &$this->backend->getData();
 279                 return array_key_exists( $key, $data ) ? $data[$key] : $default;
 280         }
 281
 282         /**
 283          * Test if a value exists in the session
 284          * @param string|int $key
 285          * @return bool
 286          */
 287         public function exists( $key ) {
 288                 $data = &$this->backend->getData();
 289                 return array_key_exists( $key, $data );
 290         }
 291
 292         /**
 293          * Set a value in the session
 294          * @param string|int $key
 295          * @param mixed $value
 296          */
 297         public function set( $key, $value ) {
 298                 $data = &$this->backend->getData();
 299                 if ( !array_key_exists( $key, $data ) || $data[$key] !== $value ) {
 300                         $data[$key] = $value;
 301                         $this->backend->dirty();
 302                 }
 303         }
 304
 305         /**
 306          * Remove a value from the session
 307          * @param string|int $key
 308          */
 309         public function remove( $key ) {
 310                 $data = &$this->backend->getData();
 311                 if ( array_key_exists( $key, $data ) ) {
 312                         unset( $data[$key] );
 313                         $this->backend->dirty();
 314                 }
 315         }
 316
 317         /**
 318          * Fetch a CSRF token from the session
 319          *
 320          * Note that this does not persist the session, which you'll probably want
 321          * to do if you want the token to actually be useful.
 322          *
 323          * @param string|string[] $salt Token salt
 324          * @param string $key Token key
 325          * @return MediaWiki\\Session\\SessionToken
 326          */
 327         public function getToken( $salt = '', $key = 'default' ) {
 328                 $new = false;
 329                 $secrets = $this->get( 'wsTokenSecrets' );
 330                 if ( !is_array( $secrets ) ) {
 331                         $secrets = array();
 332                 }
 333                 if ( isset( $secrets[$key] ) && is_string( $secrets[$key] ) ) {
 334                         $secret = $secrets[$key];
 335                 } else {
 336                         $secret = \MWCryptRand::generateHex( 32 );
 337                         $secrets[$key] = $secret;
 338                         $this->set( 'wsTokenSecrets', $secrets );
 339                         $new = true;
 340                 }
 341                 if ( is_array( $salt ) ) {
 342                         $salt = join( '|', $salt );
 343                 }
 344                 return new Token( $secret, (string)$salt, $new );
 345         }
 346
 347         /**
 348          * Remove a CSRF token from the session
 349          *
 350          * The next call to self::getToken() with $key will generate a new secret.
 351          *
 352          * @param string $key Token key
 353          */
 354         public function resetToken( $key = 'default' ) {
 355                 $secrets = $this->get( 'wsTokenSecrets' );
 356                 if ( is_array( $secrets ) && isset( $secrets[$key] ) ) {
 357                         unset( $secrets[$key] );
 358                         $this->set( 'wsTokenSecrets', $secrets );
 359                 }
 360         }
 361
 362         /**
 363          * Remove all CSRF tokens from the session
 364          */
 365         public function resetAllTokens() {
 366                 $this->remove( 'wsTokenSecrets' );
 367         }
 368
 369         /**
 370          * Delay automatic saving while multiple updates are being made
 371          *
 372          * Calls to save() or clear() will not be delayed.
 373          *
 374          * @return \ScopedCallback When this goes out of scope, a save will be triggered
 375          */
 376         public function delaySave() {
 377                 return $this->backend->delaySave();
 378         }
 379
 380         /**
 381          * Save the session
 382          */
 383         public function save() {
 384                 $this->backend->save();
 385         }
 386
 387         /**
 388          * @name Interface methods
 389          * @{
 390          */
 391
 392         public function count() {
 393                 $data = &$this->backend->getData();
 394                 return count( $data );
 395         }
 396
 397         public function current() {
 398                 $data = &$this->backend->getData();
 399                 return current( $data );
 400         }
 401
 402         public function key() {
 403                 $data = &$this->backend->getData();
 404                 return key( $data );
 405         }
 406
 407         public function next() {
 408                 $data = &$this->backend->getData();
 409                 next( $data );
 410         }
 411
 412         public function rewind() {
 413                 $data = &$this->backend->getData();
 414                 reset( $data );
 415         }
 416
 417         public function valid() {
 418                 $data = &$this->backend->getData();
 419                 return key( $data ) !== null;
 420         }
 421
 422         /**@}*/
 423
 424 }