From e3345398aafe2903faa997a5c47c275197d92cfa Mon Sep 17 00:00:00 2001 From: Andrew Nacin Date: Wed, 27 Aug 2014 02:06:53 +0000 Subject: [PATCH] Rename the public methods in the session tokens API. Introduces a new get( $token ) method. get_token() would not have made sense and spurred the overall renaming. Public methods are now get, get_all, verify, create, update, destroy, destroy_others, and destroy_all. The protected abstract methods designed for alternative implementations remain the same. props mdawaffe. see #20276. git-svn-id: https://develop.svn.wordpress.org/trunk@29635 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/pluggable.php | 6 +-- src/wp-includes/session.php | 79 +++++++++++++++++----------- src/wp-includes/user.php | 8 +-- tests/phpunit/tests/user/session.php | 44 ++++++++-------- 4 files changed, 78 insertions(+), 59 deletions(-) diff --git a/src/wp-includes/pluggable.php b/src/wp-includes/pluggable.php index 8f20f7037f..872da82ad0 100644 --- a/src/wp-includes/pluggable.php +++ b/src/wp-includes/pluggable.php @@ -684,7 +684,7 @@ function wp_validate_auth_cookie($cookie = '', $scheme = '') { } $manager = WP_Session_Tokens::get_instance( $user->ID ); - if ( ! $manager->verify_token( $token ) ) { + if ( ! $manager->verify( $token ) ) { do_action( 'auth_cookie_bad_session_token', $cookie_elements ); return false; } @@ -728,7 +728,7 @@ function wp_generate_auth_cookie( $user_id, $expiration, $scheme = 'auth', $toke if ( ! $token ) { $manager = WP_Session_Tokens::get_instance( $user_id ); - $token = $manager->create_token( $expiration ); + $token = $manager->create( $expiration ); } $pass_frag = substr($user->user_pass, 8, 4); @@ -877,7 +877,7 @@ function wp_set_auth_cookie($user_id, $remember = false, $secure = '') { } $manager = WP_Session_Tokens::get_instance( $user_id ); - $token = $manager->create_token( $expiration ); + $token = $manager->create( $expiration ); $auth_cookie = wp_generate_auth_cookie( $user_id, $expiration, $scheme, $token ); $logged_in_cookie = wp_generate_auth_cookie( $user_id, $expiration, 'logged_in', $token ); diff --git a/src/wp-includes/session.php b/src/wp-includes/session.php index 54847b461f..dca4d94e9a 100644 --- a/src/wp-includes/session.php +++ b/src/wp-includes/session.php @@ -18,6 +18,8 @@ abstract class WP_Session_Tokens { /** * Protected constructor. * + * @since 4.0.0 + * * @param int $user_id User whose session to manage. */ protected function __construct( $user_id ) { @@ -50,18 +52,32 @@ abstract class WP_Session_Tokens { } /** - * Hashes a token for storage. + * Hashes a session token for storage. * * @since 4.0.0 * @access private * - * @param string $token Token to hash. - * @return string A hash of the token (a verifier). + * @param string $token Session token to hash. + * @return string A hash of the session token (a verifier). */ final private function hash_token( $token ) { return hash( 'sha256', $token ); } + /** + * Get a user's session. + * + * @since 4.0.0 + * @access public + * + * @param string $token Session token + * @return array User session + */ + final public function get( $token ) { + $verifier = $this->hash_token( $token ); + return $this->get_session( $verifier ); + } + /** * Validate a user's session token as authentic. * @@ -73,26 +89,29 @@ abstract class WP_Session_Tokens { * @param string $token Token to verify. * @return bool Whether the token is valid for the user. */ - final public function verify_token( $token ) { + final public function verify( $token ) { $verifier = $this->hash_token( $token ); return (bool) $this->get_session( $verifier ); } /** - * Generate a cookie session identification token. + * Generate a session token and attach session information to it. * - * A session identification token is a long, random string. It is used to - * link a cookie to an expiration time and to ensure that cookies become - * invalidated upon logout. This function generates a token and stores it - * with the associated expiration time. + * A session token is a long, random string. It is used in a cookie + * link that cookie to an expiration time and to ensure the cookie + * becomes invalidated upon logout. + * + * This function generates a token and stores it with the associated + * expiration time (and potentially other session information via the + * `attach_session_information` filter). * * @since 4.0.0 * @access public * * @param int $expiration Session expiration timestamp. - * @return string Session identification token. + * @return string Session token. */ - final public function create_token( $expiration ) { + final public function create( $expiration ) { /** * Filter the information attached to the newly created session. * @@ -109,21 +128,21 @@ abstract class WP_Session_Tokens { $token = wp_generate_password( 43, false, false ); - $this->update_token( $token, $session ); + $this->update( $token, $session ); return $token; } /** - * Updates a session based on its token. + * Update a session token. * * @since 4.0.0 * @access public * - * @param string $token Token to update. + * @param string $token Session token to update. * @param array $session Session information. */ - final public function update_token( $token, $session ) { + final public function update( $token, $session ) { $verifier = $this->hash_token( $token ); $this->update_session( $verifier, $session ); } @@ -134,9 +153,9 @@ abstract class WP_Session_Tokens { * @since 4.0.0 * @access public * - * @param string $token Token to destroy. + * @param string $token Session token to destroy. */ - final public function destroy_token( $token ) { + final public function destroy( $token ) { $verifier = $this->hash_token( $token ); $this->update_session( $verifier, null ); } @@ -148,15 +167,15 @@ abstract class WP_Session_Tokens { * @since 4.0.0 * @access public * - * @param string $token_to_keep Token to keep. + * @param string $token_to_keep Session token to keep. */ - final public function destroy_other_tokens( $token_to_keep ) { + final public function destroy_others( $token_to_keep ) { $verifier = $this->hash_token( $token_to_keep ); $session = $this->get_session( $verifier ); if ( $session ) { $this->destroy_other_sessions( $verifier ); } else { - $this->destroy_all_tokens(); + $this->destroy_all_sessions(); } } @@ -175,23 +194,23 @@ abstract class WP_Session_Tokens { } /** - * Destroy all tokens for a user. + * Destroy all session tokens for a user. * * @since 4.0.0 * @access public */ - final public function destroy_all_tokens() { + final public function destroy_all() { $this->destroy_all_sessions(); } /** - * Destroy all tokens for all users. + * Destroy all session tokens for all users. * * @since 4.0.0 * @access public * @static */ - final public static function destroy_all_tokens_for_all_users() { + final public static function destroy_all_for_all_users() { $manager = apply_filters( 'session_token_manager', 'WP_User_Meta_Session_Tokens' ); call_user_func( array( $manager, 'drop_sessions' ) ); } @@ -204,7 +223,7 @@ abstract class WP_Session_Tokens { * * @return array Sessions of a user. */ - final public function get_all_sessions() { + final public function get_all() { return array_values( $this->get_sessions() ); } @@ -224,7 +243,7 @@ abstract class WP_Session_Tokens { * @since 4.0.0 * @access protected * - * @param $verifier Verifier of the session to retrieve. + * @param string $verifier Verifier of the session to retrieve. * @return array|null The session, or null if it does not exist. */ abstract protected function get_session( $verifier ); @@ -237,7 +256,7 @@ abstract class WP_Session_Tokens { * @since 4.0.0 * @access protected * - * @param $verifier Verifier of the session to update. + * @param string $verifier Verifier of the session to update. */ abstract protected function update_session( $verifier, $session = null ); @@ -248,7 +267,7 @@ abstract class WP_Session_Tokens { * @since 4.0.0 * @access protected * - * @param $verifier Verifier of the session to keep. + * @param string $verifier Verifier of the session to keep. */ abstract protected function destroy_other_sessions( $verifier ); @@ -316,7 +335,7 @@ class WP_User_Meta_Session_Tokens extends WP_Session_Tokens { * @since 4.0.0 * @access protected * - * @param $verifier Verifier of the session to retrieve. + * @param string $verifier Verifier of the session to retrieve. * @return array|null The session, or null if it does not exist */ protected function get_session( $verifier ) { @@ -376,7 +395,7 @@ class WP_User_Meta_Session_Tokens extends WP_Session_Tokens { * @since 4.0.0 * @access protected * - * @param $verifier Verifier of the session to keep. + * @param string $verifier Verifier of the session to keep. */ protected function destroy_other_sessions( $verifier ) { $session = $this->get_session( $verifier ); diff --git a/src/wp-includes/user.php b/src/wp-includes/user.php index dbde67ee6c..af0286457f 100644 --- a/src/wp-includes/user.php +++ b/src/wp-includes/user.php @@ -2207,7 +2207,7 @@ function wp_get_session_token() { */ function wp_get_all_sessions() { $manager = WP_Session_Tokens::get_instance( get_current_user_id() ); - return $manager->get_all_sessions(); + return $manager->get_all(); } /** @@ -2219,7 +2219,7 @@ function wp_destroy_current_session() { $token = wp_get_session_token(); if ( $token ) { $manager = WP_Session_Tokens::get_instance( get_current_user_id() ); - $manager->destroy_token( $token ); + $manager->destroy( $token ); } } @@ -2232,7 +2232,7 @@ function wp_destroy_other_sessions() { $token = wp_get_session_token(); if ( $token ) { $manager = WP_Session_Tokens::get_instance( get_current_user_id() ); - $manager->destroy_other_tokens( $token ); + $manager->destroy_others( $token ); } } @@ -2243,5 +2243,5 @@ function wp_destroy_other_sessions() { */ function wp_destroy_all_sessions() { $manager = WP_Session_Tokens::get_instance( get_current_user_id() ); - $manager->destroy_all_tokens(); + $manager->destroy_all(); } diff --git a/tests/phpunit/tests/user/session.php b/tests/phpunit/tests/user/session.php index f25b3d494a..565676f56f 100644 --- a/tests/phpunit/tests/user/session.php +++ b/tests/phpunit/tests/user/session.php @@ -18,35 +18,35 @@ class Tests_User_Session extends WP_UnitTestCase { function test_verify_and_destroy_token() { $expiration = time() + DAY_IN_SECONDS; - $token = $this->manager->create_token( $expiration ); - $this->assertFalse( $this->manager->verify_token( 'foo' ) ); - $this->assertTrue( $this->manager->verify_token( $token ) ); - $this->manager->destroy_token( $token ); - $this->assertFalse( $this->manager->verify_token( $token ) ); + $token = $this->manager->create( $expiration ); + $this->assertFalse( $this->manager->verify( 'foo' ) ); + $this->assertTrue( $this->manager->verify( $token ) ); + $this->manager->destroy( $token ); + $this->assertFalse( $this->manager->verify( $token ) ); } function test_destroy_other_tokens() { $expiration = time() + DAY_IN_SECONDS; - $token_1 = $this->manager->create_token( $expiration ); - $token_2 = $this->manager->create_token( $expiration ); - $token_3 = $this->manager->create_token( $expiration ); - $this->assertTrue( $this->manager->verify_token( $token_1 ) ); - $this->assertTrue( $this->manager->verify_token( $token_2 ) ); - $this->assertTrue( $this->manager->verify_token( $token_3 ) ); - $this->manager->destroy_other_tokens( $token_2 ); - $this->assertFalse( $this->manager->verify_token( $token_1 ) ); - $this->assertTrue( $this->manager->verify_token( $token_2 ) ); - $this->assertFalse( $this->manager->verify_token( $token_3 ) ); + $token_1 = $this->manager->create( $expiration ); + $token_2 = $this->manager->create( $expiration ); + $token_3 = $this->manager->create( $expiration ); + $this->assertTrue( $this->manager->verify( $token_1 ) ); + $this->assertTrue( $this->manager->verify( $token_2 ) ); + $this->assertTrue( $this->manager->verify( $token_3 ) ); + $this->manager->destroy_others( $token_2 ); + $this->assertFalse( $this->manager->verify( $token_1 ) ); + $this->assertTrue( $this->manager->verify( $token_2 ) ); + $this->assertFalse( $this->manager->verify( $token_3 ) ); } function test_destroy_all_tokens() { $expiration = time() + DAY_IN_SECONDS; - $token_1 = $this->manager->create_token( $expiration ); - $token_2 = $this->manager->create_token( $expiration ); - $this->assertTrue( $this->manager->verify_token( $token_1 ) ); - $this->assertTrue( $this->manager->verify_token( $token_2 ) ); - $this->manager->destroy_all_tokens(); - $this->assertFalse( $this->manager->verify_token( $token_1 ) ); - $this->assertFalse( $this->manager->verify_token( $token_2 ) ); + $token_1 = $this->manager->create( $expiration ); + $token_2 = $this->manager->create( $expiration ); + $this->assertTrue( $this->manager->verify( $token_1 ) ); + $this->assertTrue( $this->manager->verify( $token_2 ) ); + $this->manager->destroy_all(); + $this->assertFalse( $this->manager->verify( $token_1 ) ); + $this->assertFalse( $this->manager->verify( $token_2 ) ); } }