[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Session API: WP_Session_Tokens class
   4   *
   5   * @package WordPress
   6   * @subpackage Session
   7   * @since 4.7.0
   8   */
   9  
  10  /**
  11   * Abstract class for managing user session tokens.
  12   *
  13   * @since 4.0.0
  14   */
  15  abstract class WP_Session_Tokens {
  16  
  17      /**
  18       * User ID.
  19       *
  20       * @since 4.0.0
  21       * @var int User ID.
  22       */
  23      protected $user_id;
  24  
  25      /**
  26       * Protected constructor. Use the `get_instance()` method to get the instance.
  27       *
  28       * @since 4.0.0
  29       *
  30       * @param int $user_id User whose session to manage.
  31       */
  32  	protected function __construct( $user_id ) {
  33          $this->user_id = $user_id;
  34      }
  35  
  36      /**
  37       * Retrieves a session manager instance for a user.
  38       *
  39       * This method contains a {@see 'session_token_manager'} filter, allowing a plugin to swap out
  40       * the session manager for a subclass of `WP_Session_Tokens`.
  41       *
  42       * @since 4.0.0
  43       *
  44       * @param int $user_id User whose session to manage.
  45       * @return WP_Session_Tokens The session object, which is by default an instance of
  46       *                           the `WP_User_Meta_Session_Tokens` class.
  47       */
  48  	final public static function get_instance( $user_id ) {
  49          /**
  50           * Filters the class name for the session token manager.
  51           *
  52           * @since 4.0.0
  53           *
  54           * @param string $session Name of class to use as the manager.
  55           *                        Default 'WP_User_Meta_Session_Tokens'.
  56           */
  57          $manager = apply_filters( 'session_token_manager', 'WP_User_Meta_Session_Tokens' );
  58          return new $manager( $user_id );
  59      }
  60  
  61      /**
  62       * Hashes the given session token for storage.
  63       *
  64       * @since 4.0.0
  65       *
  66       * @param string $token Session token to hash.
  67       * @return string A hash of the session token (a verifier).
  68       */
  69  	private function hash_token( $token ) {
  70          // If ext/hash is not present, use sha1() instead.
  71          if ( function_exists( 'hash' ) ) {
  72              return hash( 'sha256', $token );
  73          } else {
  74              return sha1( $token );
  75          }
  76      }
  77  
  78      /**
  79       * Retrieves a user's session for the given token.
  80       *
  81       * @since 4.0.0
  82       *
  83       * @param string $token Session token.
  84       * @return array|null The session, or null if it does not exist.
  85       */
  86  	final public function get( $token ) {
  87          $verifier = $this->hash_token( $token );
  88          return $this->get_session( $verifier );
  89      }
  90  
  91      /**
  92       * Validates the given session token for authenticity and validity.
  93       *
  94       * Checks that the given token is present and hasn't expired.
  95       *
  96       * @since 4.0.0
  97       *
  98       * @param string $token Token to verify.
  99       * @return bool Whether the token is valid for the user.
 100       */
 101  	final public function verify( $token ) {
 102          $verifier = $this->hash_token( $token );
 103          return (bool) $this->get_session( $verifier );
 104      }
 105  
 106      /**
 107       * Generates a session token and attaches session information to it.
 108       *
 109       * A session token is a long, random string. It is used in a cookie
 110       * to link that cookie to an expiration time and to ensure the cookie
 111       * becomes invalidated when the user logs out.
 112       *
 113       * This function generates a token and stores it with the associated
 114       * expiration time (and potentially other session information via the
 115       * {@see 'attach_session_information'} filter).
 116       *
 117       * @since 4.0.0
 118       *
 119       * @param int $expiration Session expiration timestamp.
 120       * @return string Session token.
 121       */
 122  	final public function create( $expiration ) {
 123          /**
 124           * Filters the information attached to the newly created session.
 125           *
 126           * Can be used to attach further information to a session.
 127           *
 128           * @since 4.0.0
 129           *
 130           * @param array $session Array of extra data.
 131           * @param int   $user_id User ID.
 132           */
 133          $session               = apply_filters( 'attach_session_information', array(), $this->user_id );
 134          $session['expiration'] = $expiration;
 135  
 136          // IP address.
 137          if ( ! empty( $_SERVER['REMOTE_ADDR'] ) ) {
 138              $session['ip'] = $_SERVER['REMOTE_ADDR'];
 139          }
 140  
 141          // User-agent.
 142          if ( ! empty( $_SERVER['HTTP_USER_AGENT'] ) ) {
 143              $session['ua'] = wp_unslash( $_SERVER['HTTP_USER_AGENT'] );
 144          }
 145  
 146          // Timestamp.
 147          $session['login'] = time();
 148  
 149          $token = wp_generate_password( 43, false, false );
 150  
 151          $this->update( $token, $session );
 152  
 153          return $token;
 154      }
 155  
 156      /**
 157       * Updates the data for the session with the given token.
 158       *
 159       * @since 4.0.0
 160       *
 161       * @param string $token Session token to update.
 162       * @param array  $session Session information.
 163       */
 164  	final public function update( $token, $session ) {
 165          $verifier = $this->hash_token( $token );
 166          $this->update_session( $verifier, $session );
 167      }
 168  
 169      /**
 170       * Destroys the session with the given token.
 171       *
 172       * @since 4.0.0
 173       *
 174       * @param string $token Session token to destroy.
 175       */
 176  	final public function destroy( $token ) {
 177          $verifier = $this->hash_token( $token );
 178          $this->update_session( $verifier, null );
 179      }
 180  
 181      /**
 182       * Destroys all sessions for this user except the one with the given token (presumably the one in use).
 183       *
 184       * @since 4.0.0
 185       *
 186       * @param string $token_to_keep Session token to keep.
 187       */
 188  	final public function destroy_others( $token_to_keep ) {
 189          $verifier = $this->hash_token( $token_to_keep );
 190          $session  = $this->get_session( $verifier );
 191          if ( $session ) {
 192              $this->destroy_other_sessions( $verifier );
 193          } else {
 194              $this->destroy_all_sessions();
 195          }
 196      }
 197  
 198      /**
 199       * Determines whether a session is still valid, based on its expiration timestamp.
 200       *
 201       * @since 4.0.0
 202       *
 203       * @param array $session Session to check.
 204       * @return bool Whether session is valid.
 205       */
 206  	final protected function is_still_valid( $session ) {
 207          return $session['expiration'] >= time();
 208      }
 209  
 210      /**
 211       * Destroys all sessions for a user.
 212       *
 213       * @since 4.0.0
 214       */
 215  	final public function destroy_all() {
 216          $this->destroy_all_sessions();
 217      }
 218  
 219      /**
 220       * Destroys all sessions for all users.
 221       *
 222       * @since 4.0.0
 223       */
 224  	final public static function destroy_all_for_all_users() {
 225          /** This filter is documented in wp-includes/class-wp-session-tokens.php */
 226          $manager = apply_filters( 'session_token_manager', 'WP_User_Meta_Session_Tokens' );
 227          call_user_func( array( $manager, 'drop_sessions' ) );
 228      }
 229  
 230      /**
 231       * Retrieves all sessions for a user.
 232       *
 233       * @since 4.0.0
 234       *
 235       * @return array Sessions for a user.
 236       */
 237  	final public function get_all() {
 238          return array_values( $this->get_sessions() );
 239      }
 240  
 241      /**
 242       * Retrieves all sessions of the user.
 243       *
 244       * @since 4.0.0
 245       *
 246       * @return array Sessions of the user.
 247       */
 248      abstract protected function get_sessions();
 249  
 250      /**
 251       * Retrieves a session based on its verifier (token hash).
 252       *
 253       * @since 4.0.0
 254       *
 255       * @param string $verifier Verifier for the session to retrieve.
 256       * @return array|null The session, or null if it does not exist.
 257       */
 258      abstract protected function get_session( $verifier );
 259  
 260      /**
 261       * Updates a session based on its verifier (token hash).
 262       *
 263       * Omitting the second argument destroys the session.
 264       *
 265       * @since 4.0.0
 266       *
 267       * @param string $verifier Verifier for the session to update.
 268       * @param array  $session  Optional. Session. Omitting this argument destroys the session.
 269       */
 270      abstract protected function update_session( $verifier, $session = null );
 271  
 272      /**
 273       * Destroys all sessions for this user, except the single session with the given verifier.
 274       *
 275       * @since 4.0.0
 276       *
 277       * @param string $verifier Verifier of the session to keep.
 278       */
 279      abstract protected function destroy_other_sessions( $verifier );
 280  
 281      /**
 282       * Destroys all sessions for the user.
 283       *
 284       * @since 4.0.0
 285       */
 286      abstract protected function destroy_all_sessions();
 287  
 288      /**
 289       * Destroys all sessions for all users.
 290       *
 291       * @since 4.0.0
 292       */
 293  	public static function drop_sessions() {}
 294  }