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