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          * Indicate whether the session user info can be changed
 158          * @return bool
 159          */
 160         public function canSetUser() {
 161                 return $this->backend->canSetUser();
 162         }
 163
 164         /**
 165          * Set a new user for this session
 166          * @note This should only be called when the user has been authenticated
 167          * @param User $user User to set on the session.
 168          *   This may become a "UserValue" in the future, or User may be refactored
 169          *   into such.
 170          */
 171         public function setUser( $user ) {
 172                 $this->backend->setUser( $user );
 173         }
 174
 175         /**
 176          * Get a suggested username for the login form
 177          * @return string|null
 178          */
 179         public function suggestLoginUsername() {
 180                 return $this->backend->suggestLoginUsername( $this->index );
 181         }
 182
 183         /**
 184          * Whether HTTPS should be forced
 185          * @return bool
 186          */
 187         public function shouldForceHTTPS() {
 188                 return $this->backend->shouldForceHTTPS();
 189         }
 190
 191         /**
 192          * Set whether HTTPS should be forced
 193          * @param bool $force
 194          */
 195         public function setForceHTTPS( $force ) {
 196                 $this->backend->setForceHTTPS( $force );
 197         }
 198
 199         /**
 200          * Fetch the "logged out" timestamp
 201          * @return int
 202          */
 203         public function getLoggedOutTimestamp() {
 204                 return $this->backend->getLoggedOutTimestamp();
 205         }
 206
 207         /**
 208          * Set the "logged out" timestamp
 209          * @param int $ts
 210          */
 211         public function setLoggedOutTimestamp( $ts ) {
 212                 $this->backend->setLoggedOutTimestamp( $ts );
 213         }
 214
 215         /**
 216          * Fetch provider metadata
 217          * @protected For use by SessionProvider subclasses only
 218          * @return mixed
 219          */
 220         public function getProviderMetadata() {
 221                 return $this->backend->getProviderMetadata();
 222         }
 223
 224         /**
 225          * Delete all session data and clear the user (if possible)
 226          */
 227         public function clear() {
 228                 $data = &$this->backend->getData();
 229                 if ( $data ) {
 230                         $data = array();
 231                         $this->backend->dirty();
 232                 }
 233                 if ( $this->backend->canSetUser() ) {
 234                         $this->backend->setUser( new User );
 235                 }
 236                 $this->backend->save();
 237         }
 238
 239         /**
 240          * Renew the session
 241          *
 242          * Resets the TTL in the backend store if the session is near expiring, and
 243          * re-persists the session to any active WebRequests if persistent.
 244          */
 245         public function renew() {
 246                 $this->backend->renew();
 247         }
 248
 249         /**
 250          * Fetch a copy of this session attached to an alternative WebRequest
 251          *
 252          * Actions on the copy will affect this session too, and vice versa.
 253          *
 254          * @param WebRequest $request Any existing session associated with this
 255          *  WebRequest object will be overwritten.
 256          * @return Session
 257          */
 258         public function sessionWithRequest( WebRequest $request ) {
 259                 $request->setSessionId( $this->backend->getSessionId() );
 260                 return $this->backend->getSession( $request );
 261         }
 262
 263         /**
 264          * Fetch a value from the session
 265          * @param string|int $key
 266          * @param mixed $default
 267          * @return mixed
 268          */
 269         public function get( $key, $default = null ) {
 270                 $data = &$this->backend->getData();
 271                 return array_key_exists( $key, $data ) ? $data[$key] : $default;
 272         }
 273
 274         /**
 275          * Test if a value exists in the session
 276          * @param string|int $key
 277          * @return bool
 278          */
 279         public function exists( $key ) {
 280                 $data = &$this->backend->getData();
 281                 return array_key_exists( $key, $data );
 282         }
 283
 284         /**
 285          * Set a value in the session
 286          * @param string|int $key
 287          * @param mixed $value
 288          */
 289         public function set( $key, $value ) {
 290                 $data = &$this->backend->getData();
 291                 if ( !array_key_exists( $key, $data ) || $data[$key] !== $value ) {
 292                         $data[$key] = $value;
 293                         $this->backend->dirty();
 294                 }
 295         }
 296
 297         /**
 298          * Remove a value from the session
 299          * @param string|int $key
 300          */
 301         public function remove( $key ) {
 302                 $data = &$this->backend->getData();
 303                 if ( array_key_exists( $key, $data ) ) {
 304                         unset( $data[$key] );
 305                         $this->backend->dirty();
 306                 }
 307         }
 308
 309         /**
 310          * Delay automatic saving while multiple updates are being made
 311          *
 312          * Calls to save() or clear() will not be delayed.
 313          *
 314          * @return \ScopedCallback When this goes out of scope, a save will be triggered
 315          */
 316         public function delaySave() {
 317                 return $this->backend->delaySave();
 318         }
 319
 320         /**
 321          * Save the session
 322          */
 323         public function save() {
 324                 $this->backend->save();
 325         }
 326
 327         /**
 328          * @name Interface methods
 329          * @{
 330          */
 331
 332         public function count() {
 333                 $data = &$this->backend->getData();
 334                 return count( $data );
 335         }
 336
 337         public function current() {
 338                 $data = &$this->backend->getData();
 339                 return current( $data );
 340         }
 341
 342         public function key() {
 343                 $data = &$this->backend->getData();
 344                 return key( $data );
 345         }
 346
 347         public function next() {
 348                 $data = &$this->backend->getData();
 349                 next( $data );
 350         }
 351
 352         public function rewind() {
 353                 $data = &$this->backend->getData();
 354                 reset( $data );
 355         }
 356
 357         public function valid() {
 358                 $data = &$this->backend->getData();
 359                 return key( $data ) !== null;
 360         }
 361
 362         /**@}*/
 363
 364 }