3 * Abstract class for managing user session tokens.
7 abstract class WP_Session_Tokens {
19 * Protected constructor.
23 * @param int $user_id User whose session to manage.
25 protected function __construct( $user_id ) {
26 $this->user_id = $user_id;
30 * Get a session token manager instance for a user.
32 * This method contains a filter that allows a plugin to swap out
33 * the session manager for a subclass of WP_Session_Tokens.
39 * @param int $user_id User whose session to manage.
41 final public static function get_instance( $user_id ) {
43 * Filter the session token manager used.
47 * @param string $session Name of class to use as the manager.
48 * Default 'WP_User_Meta_Session_Tokens'.
50 $manager = apply_filters( 'session_token_manager', 'WP_User_Meta_Session_Tokens' );
51 return new $manager( $user_id );
55 * Hashes a session token for storage.
60 * @param string $token Session token to hash.
61 * @return string A hash of the session token (a verifier).
63 final private function hash_token( $token ) {
64 return hash( 'sha256', $token );
68 * Get a user's session.
73 * @param string $token Session token
74 * @return array User session
76 final public function get( $token ) {
77 $verifier = $this->hash_token( $token );
78 return $this->get_session( $verifier );
82 * Validate a user's session token as authentic.
84 * Checks that the given token is present and hasn't expired.
89 * @param string $token Token to verify.
90 * @return bool Whether the token is valid for the user.
92 final public function verify( $token ) {
93 $verifier = $this->hash_token( $token );
94 return (bool) $this->get_session( $verifier );
98 * Generate a session token and attach session information to it.
100 * A session token is a long, random string. It is used in a cookie
101 * link that cookie to an expiration time and to ensure the cookie
102 * becomes invalidated upon logout.
104 * This function generates a token and stores it with the associated
105 * expiration time (and potentially other session information via the
106 * `attach_session_information` filter).
111 * @param int $expiration Session expiration timestamp.
112 * @return string Session token.
114 final public function create( $expiration ) {
116 * Filter the information attached to the newly created session.
118 * Could be used in the future to attach information such as
119 * IP address or user agent to a session.
123 * @param array $session Array of extra data.
124 * @param int $user_id User ID.
126 $session = apply_filters( 'attach_session_information', array(), $this->user_id );
127 $session['expiration'] = $expiration;
129 $token = wp_generate_password( 43, false, false );
131 $this->update( $token, $session );
137 * Update a session token.
142 * @param string $token Session token to update.
143 * @param array $session Session information.
145 final public function update( $token, $session ) {
146 $verifier = $this->hash_token( $token );
147 $this->update_session( $verifier, $session );
151 * Destroy a session token.
156 * @param string $token Session token to destroy.
158 final public function destroy( $token ) {
159 $verifier = $this->hash_token( $token );
160 $this->update_session( $verifier, null );
164 * Destroy all session tokens for this user,
165 * except a single token, presumably the one in use.
170 * @param string $token_to_keep Session token to keep.
172 final public function destroy_others( $token_to_keep ) {
173 $verifier = $this->hash_token( $token_to_keep );
174 $session = $this->get_session( $verifier );
176 $this->destroy_other_sessions( $verifier );
178 $this->destroy_all_sessions();
183 * Determine whether a session token is still valid,
184 * based on expiration.
189 * @param array $session Session to check.
190 * @return bool Whether session is valid.
192 final protected function is_still_valid( $session ) {
193 return $session['expiration'] >= time();
197 * Destroy all session tokens for a user.
202 final public function destroy_all() {
203 $this->destroy_all_sessions();
207 * Destroy all session tokens for all users.
213 final public static function destroy_all_for_all_users() {
214 $manager = apply_filters( 'session_token_manager', 'WP_User_Meta_Session_Tokens' );
215 call_user_func( array( $manager, 'drop_sessions' ) );
219 * Retrieve all sessions of a user.
224 * @return array Sessions of a user.
226 final public function get_all() {
227 return array_values( $this->get_sessions() );
231 * This method should retrieve all sessions of a user, keyed by verifier.
236 * @return array Sessions of a user, keyed by verifier.
238 abstract protected function get_sessions();
241 * This method should look up a session by its verifier (token hash).
246 * @param string $verifier Verifier of the session to retrieve.
247 * @return array|null The session, or null if it does not exist.
249 abstract protected function get_session( $verifier );
252 * This method should update a session by its verifier.
254 * Omitting the second argument should destroy the session.
259 * @param string $verifier Verifier of the session to update.
261 abstract protected function update_session( $verifier, $session = null );
264 * This method should destroy all session tokens for this user,
265 * except a single session passed.
270 * @param string $verifier Verifier of the session to keep.
272 abstract protected function destroy_other_sessions( $verifier );
275 * This method should destroy all sessions for a user.
280 abstract protected function destroy_all_sessions();
283 * This static method should destroy all session tokens for all users.
289 public static function drop_sessions() {}
293 * Meta-based user sessions token manager.
297 class WP_User_Meta_Session_Tokens extends WP_Session_Tokens {
300 * Get all sessions of a user.
305 * @return array Sessions of a user.
307 protected function get_sessions() {
308 $sessions = get_user_meta( $this->user_id, 'session_tokens', true );
310 if ( ! is_array( $sessions ) ) {
314 $sessions = array_map( array( $this, 'prepare_session' ), $sessions );
315 return array_filter( $sessions, array( $this, 'is_still_valid' ) );
319 * Converts an expiration to an array of session information.
321 * @param mixed $session Session or expiration.
322 * @return array Session.
324 protected function prepare_session( $session ) {
325 if ( is_int( $session ) ) {
326 return array( 'expiration' => $session );
333 * Retrieve a session by its verifier (token hash).
338 * @param string $verifier Verifier of the session to retrieve.
339 * @return array|null The session, or null if it does not exist
341 protected function get_session( $verifier ) {
342 $sessions = $this->get_sessions();
344 if ( isset( $sessions[ $verifier ] ) ) {
345 return $sessions[ $verifier ];
352 * Update a session by its verifier.
357 * @param string $verifier Verifier of the session to update.
358 * @param array $session Optional. Session. Omitting this argument destroys the session.
360 protected function update_session( $verifier, $session = null ) {
361 $sessions = $this->get_sessions();
364 $sessions[ $verifier ] = $session;
366 unset( $sessions[ $verifier ] );
369 $this->update_sessions( $sessions );
373 * Update a user's sessions in the usermeta table.
378 * @param array $sessions Sessions.
380 protected function update_sessions( $sessions ) {
381 if ( ! has_filter( 'attach_session_information' ) ) {
382 $sessions = wp_list_pluck( $sessions, 'expiration' );
386 update_user_meta( $this->user_id, 'session_tokens', $sessions );
388 delete_user_meta( $this->user_id, 'session_tokens' );
393 * Destroy all session tokens for a user, except a single session passed.
398 * @param string $verifier Verifier of the session to keep.
400 protected function destroy_other_sessions( $verifier ) {
401 $session = $this->get_session( $verifier );
402 $this->update_sessions( array( $verifier => $session ) );
406 * Destroy all session tokens for a user.
411 protected function destroy_all_sessions() {
412 $this->update_sessions( array() );
416 * Destroy all session tokens for all users.
422 public static function drop_sessions() {
423 delete_metadata( 'user', false, 'session_tokens', false, true );