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]
16abstract 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}
291