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