wp_xmlrpc_server::login( string $username, string $password ): WP_User|false

Compatibility

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

Parameters

$usernamestring

User's username.

$passwordstring

User's password.

Return value

WP_User|false

WP_User object if authentication passed, false otherwise.

Code examples

Every example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.

require_once ABSPATH . WPINC . '/class-wp-xmlrpc-server.php';

$server = new wp_xmlrpc_server();
$user   = $server->login( 'xmlrpc_tester', 'CorrectHorse123!' );

if ( $user instanceof WP_User ) {
	printf( 'Authenticated as %s (user ID %d).', esc_html( $user->display_name ), $user->ID );
} else {
	echo esc_html( 'Login failed.' );
}

require_once ABSPATH . WPINC . '/class-wp-xmlrpc-server.php';

add_filter( 'xmlrpc_login_error', function( $error, $user_error ) {
	return new IXR_Error( 403, 'Access denied: check your XML-RPC credentials.' );
}, 10, 2 );

$server = new wp_xmlrpc_server();
$result = $server->login( 'nobody', 'not-a-real-password' );

if ( false === $result ) {
	printf( 'Login rejected: %s', esc_html( $server->error->message ) );
}

Common problems and fixes · 4

• Why does login() keep failing even though the second password I try is correct?
• How do I read the actual error message when login() returns false?
• Why does login() fail immediately even with valid credentials?
• Does login() log a visitor in the same way a front-end login form does?

Alternatives and related functions

wp_authenticate

When you need to check a username and password without any of the XML-RPC-specific IXR_Error wrapping or the auth_failed caching.

wp_signon

When a successful login should also set an auth cookie so the user stays signed in across page loads in a browser.

wp_set_current_user

When you already have a trusted WP_User object or ID and just need to switch the current user without re-checking credentials.

wp_xmlrpc_server::login_pass_ok

When another XML-RPC server method just needs a simple pass or fail check rather than the full WP_User object login() returns.

Performance profile

How much work a call to wp_xmlrpc_server::login() 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

Trivial

Touches nothing outside its own arguments.

Scaling

Constant

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

Instructions

14–36

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

Plugin surface

1 hook

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

Called by

50

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

What it touches

• hookthird-party callbacksapply_filters()called directly

Further down the call graph this can also reach query, 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 · 5 distinct outcomes

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

Hooks and filters fired · 1

One hook fires while wp_xmlrpc_server::login() runs, in this order:

1. 1
   apply_filters( xmlrpc_login_error )filterline 325 (+30 into the body)

   Filters the XML-RPC user login error message.

Uses · 7

• __()Retrieves the translation of $text.
• wp_authenticate()Authenticates a user, confirming the login credentials are valid.
• is_wp_error()Checks whether the given variable is a WordPress Error.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• wp_set_current_user()Changes the current user by ID or name.
• IXR_Error::__construct()PHP5 constructor.
• WP_Error::__construct()Initializes the error.

Used by · 50

• wp_xmlrpc_server::blogger_deletePost()Deletes a post.
• wp_xmlrpc_server::blogger_editPost()Edits a post.
• wp_xmlrpc_server::blogger_getPost()Retrieves a post.
• wp_xmlrpc_server::blogger_getRecentPosts()Retrieves the list of recent posts.
• wp_xmlrpc_server::blogger_getUserInfo()Retrieves user's data.
• wp_xmlrpc_server::blogger_getUsersBlogs()Retrieves blogs that user owns.
• wp_xmlrpc_server::blogger_newPost()Creates a new post.
• wp_xmlrpc_server::login_pass_ok()Checks user's credentials. Deprecated.
• wp_xmlrpc_server::mt_getCategoryList()Retrieves the list of all categories on a blog.
• wp_xmlrpc_server::mt_getPostCategories()Retrieves post categories.
• wp_xmlrpc_server::mt_getRecentPostTitles()Retrieves the post titles of recent posts.
• wp_xmlrpc_server::mt_publishPost()Sets a post's publish status to 'publish'.

Source code

View on Trac ↗View on GitHub ↗

295	public function login(296		$username,297		#[\SensitiveParameter]298		$password299	) {300		if ( ! $this->is_enabled ) {301			$this->error = new IXR_Error( 405, __( 'XML-RPC services are disabled on this site.' ) );302			return false;303		}304 305		if ( $this->auth_failed ) {306			$user = new WP_Error( 'login_prevented' );307		} else {308			$user = wp_authenticate( $username, $password );309		}310 311		if ( is_wp_error( $user ) ) {312			$this->error = new IXR_Error( 403, __( 'Incorrect username or password.' ) );313 314			// Flag that authentication has failed once on this wp_xmlrpc_server instance.315			$this->auth_failed = true;316 317			/**318			 * Filters the XML-RPC user login error message.319			 *320			 * @since 3.5.0321			 *322			 * @param IXR_Error $error The XML-RPC error message.323			 * @param WP_Error  $user  WP_Error object.324			 */325			$this->error = apply_filters( 'xmlrpc_login_error', $this->error, $user );326			return false;327		}328 329		wp_set_current_user( $user->ID );330		return $user;331	}

Changelog

Introduced in 2.8.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/class-wp-xmlrpc-server.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.