WP_Session_Tokens

Abstract class for managing user session tokens.

Defined (1)

The class is defined in the following location(s).

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