wp_validate_auth_cookie( string $cookie = '', string $scheme = '' ): int|false

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$cookiestringoptional

If used, will validate contents instead of cookie's.Default: ''

$schemestringoptional

The cookie scheme to use: 'auth', 'secure_auth', or 'logged_in'.
Note: This does not default to 'auth' like other cookie functions.Default: ''

Return value

int|false

User ID if valid cookie, false if invalid.

Performance profile

How much work a call to wp_validate_auth_cookie() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via get_user_by().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

14–93

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 121.

Plugin surface

6 hooks

Third-party callbacks on 'auth_cookie_malformed', 'auth_cookie_expired', 'auth_cookie_bad_username' run inside this call, and their cost is not bounded by anything here.

Called by

3

3 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksdo_action()called directly
• querycontent queryget_user_by()called directly

Further down the call graph this can also reach option, cache, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 6 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_validate_auth_cookie() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 6

6 hooks fire while wp_validate_auth_cookie() runs, in this order:

1. 1
   do_action( auth_cookie_malformed )actionline 794 (+12 into the body)

   Fires if an authentication cookie is malformed.

2. 2
   do_action( auth_cookie_expired )actionline 829 (+47 into the body)

   Fires once an authentication cookie has expired.

3. 3
   do_action( auth_cookie_bad_username )actionline 851 (+69 into the body)

   Fires if a bad username is entered in the user authentication process.

4. 4
   do_action( auth_cookie_bad_hash )actionline 884 (+102 into the body)

   Fires if a bad authentication cookie hash is encountered.

5. 5
   do_action( auth_cookie_bad_session_token )actionline 906 (+124 into the body)

   Fires if a bad session token is encountered.

6. 6
   do_action( auth_cookie_valid )actionline 931 (+149 into the body)

   Fires once an authentication cookie has been validated.

Uses · 7

• wp_parse_auth_cookie()Parses a cookie into its components.
• do_action()Calls the callback functions that have been added to an action hook.
• wp_doing_ajax()Determines whether the current request is a WordPress Ajax request.
• get_user_by()Retrieves user info by a given field.
• str_starts_with()Polyfill for `str_starts_with()` function added in PHP 8.0.
• wp_hash()Gets the hash of the given string.
• WP_Session_Tokens::get_instance()Retrieves a session manager instance for a user.

Used by · 3

• auth_redirect()Checks if a user is logged in, if not it redirects them to the login page.
• wp_authenticate_cookie()Authenticates the user using the WordPress auth cookie.
• wp_validate_logged_in_cookie()Validates the logged-in cookie.

Source code

View on Trac ↗View on GitHub ↗

782	function wp_validate_auth_cookie( $cookie = '', $scheme = '' ) {783		$cookie_elements = wp_parse_auth_cookie( $cookie, $scheme );784		if ( ! $cookie_elements ) {785			/**786			 * Fires if an authentication cookie is malformed.787			 *788			 * @since 2.7.0789			 *790			 * @param string $cookie Malformed auth cookie.791			 * @param string $scheme Authentication scheme. Values include 'auth', 'secure_auth',792			 *                       or 'logged_in'.793			 */794			do_action( 'auth_cookie_malformed', $cookie, $scheme );795			return false;796		}797 798		$scheme     = $cookie_elements['scheme'];799		$username   = $cookie_elements['username'];800		$hmac       = $cookie_elements['hmac'];801		$token      = $cookie_elements['token'];802		$expiration = $cookie_elements['expiration'];803 804		$expired = (int) $expiration;805 806		// Allow a grace period for POST and Ajax requests.807		if ( wp_doing_ajax() || 'POST' === $_SERVER['REQUEST_METHOD'] ) {808			$expired += HOUR_IN_SECONDS;809		}810 811		// Quick check to see if an honest cookie has expired.812		if ( $expired < time() ) {813			/**814			 * Fires once an authentication cookie has expired.815			 *816			 * @since 2.7.0817			 *818			 * @param string[] $cookie_elements {819			 *     Authentication cookie components. None of the components should be assumed820			 *     to be valid as they come directly from a client-provided cookie value.821			 *822			 *     @type string $username   User's username.823			 *     @type string $expiration The time the cookie expires as a UNIX timestamp.824			 *     @type string $token      User's session token used.825			 *     @type string $hmac       The security hash for the cookie.826			 *     @type string $scheme     The cookie scheme to use.827			 * }828			 */829			do_action( 'auth_cookie_expired', $cookie_elements );830			return false;831		}832 833		$user = get_user_by( 'login', $username );834		if ( ! $user ) {835			/**836			 * Fires if a bad username is entered in the user authentication process.837			 *838			 * @since 2.7.0839			 *840			 * @param string[] $cookie_elements {841			 *     Authentication cookie components. None of the components should be assumed842			 *     to be valid as they come directly from a client-provided cookie value.843			 *844			 *     @type string $username   User's username.845			 *     @type string $expiration The time the cookie expires as a UNIX timestamp.846			 *     @type string $token      User's session token used.847			 *     @type string $hmac       The security hash for the cookie.848			 *     @type string $scheme     The cookie scheme to use.849			 * }850			 */851			do_action( 'auth_cookie_bad_username', $cookie_elements );852			return false;853		}854 855		if ( str_starts_with( $user->user_pass, '$P$' ) || str_starts_with( $user->user_pass, '$2y$' ) ) {856			// Retain previous behaviour of phpass or vanilla bcrypt hashed passwords.857			$pass_frag = substr( $user->user_pass, 8, 4 );858		} else {859			// Otherwise, use a substring from the end of the hash to avoid dealing with potentially long hash prefixes.860			$pass_frag = substr( $user->user_pass, -4 );861		}

Changelog

Introduced in 2.5.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/pluggable.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.