remove_user_from_blog( int $user_id, int $blog_id = 0, int $reassign = 0 ): true|WP_Error

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

$user_idint

ID of the user being removed.

$blog_idintoptional

ID of the blog the user is being removed from. Default 0.Default: 0

$reassignintoptional

ID of the user to whom to reassign posts. Default 0.Default: 0

Return value

true|WP_Error

True on success or a WP_Error object if the user doesn't exist.

Performance profile

How much work a call to remove_user_from_blog() 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_col().

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

40–145

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

Plugin surface

1 hook

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

Called by

5

5 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
• sqldatabase query->get_col()called directly
• cacheobject cachewp_cache_switch_to_blog()one call below remove_user_from_blog()
• optionoption read or writeget_option()one call below remove_user_from_blog()
• querycontent queryget_user_by()one call below remove_user_from_blog()

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

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

Hooks and filters fired · 1

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

1. 1
   do_action( remove_user_from_blog )actionline 257 (+18 into the body)

   Fires before a user is removed from a site.

Uses · 10

• switch_to_blog()Switches the current blog.
• do_action()Calls the callback functions that have been added to an action hook.
• get_user_meta()Retrieves user meta field for a user.
• get_blogs_of_user()Gets the sites a user belongs to.
• update_user_meta()Updates user meta field based on user ID.
• get_userdata()Retrieves user info by user ID.
• restore_current_blog()Restores the current blog, after calling switch_to_blog().
• __()Retrieves the translation of $text.
• clean_user_cache()Cleans all user caches.
• WP_Error::__construct()Initializes the error.

Used by · 5

• add_new_user_to_blog()Adds a newly created user to the appropriate blog
• wp_delete_user()Delete user and optionally reassign posts and links to another user.
• wp_uninitialize_site()Runs the uninitialization routine for a given site.
• wpmu_delete_blog()Deletes a site.
• wpmu_delete_user()Deletes a user and all of their posts from the network.

Source code

View on Trac ↗View on GitHub ↗

239function remove_user_from_blog( $user_id, $blog_id = 0, $reassign = 0 ) {240	global $wpdb;241 242	$user_id = (int) $user_id;243	$blog_id = (int) $blog_id;244 245	switch_to_blog( $blog_id );246 247	/**248	 * Fires before a user is removed from a site.249	 *250	 * @since MU (3.0.0)251	 * @since 5.4.0 Added the `$reassign` parameter.252	 *253	 * @param int $user_id  ID of the user being removed.254	 * @param int $blog_id  ID of the blog the user is being removed from.255	 * @param int $reassign ID of the user to whom to reassign posts.256	 */257	do_action( 'remove_user_from_blog', $user_id, $blog_id, $reassign );258 259	/*260	 * If being removed from the primary blog, set a new primary261	 * if the user is assigned to multiple blogs.262	 */263	$primary_blog = (int) get_user_meta( $user_id, 'primary_blog', true );264	if ( $primary_blog === $blog_id ) {265		$new_id     = '';266		$new_domain = '';267		$blogs      = get_blogs_of_user( $user_id );268		foreach ( (array) $blogs as $blog ) {269			if ( $blog->userblog_id === $blog_id ) {270				continue;271			}272			$new_id     = $blog->userblog_id;273			$new_domain = $blog->domain;274			break;275		}276 277		update_user_meta( $user_id, 'primary_blog', $new_id );278		update_user_meta( $user_id, 'source_domain', $new_domain );279	}280 281	$user = get_userdata( $user_id );282	if ( ! $user ) {283		restore_current_blog();284		return new WP_Error( 'user_does_not_exist', __( 'That user does not exist.' ) );285	}286 287	$user->remove_all_caps();288 289	$blogs = get_blogs_of_user( $user_id );290	if ( count( $blogs ) === 0 ) {291		update_user_meta( $user_id, 'primary_blog', '' );292		update_user_meta( $user_id, 'source_domain', '' );293	}294 295	if ( $reassign ) {296		$reassign = (int) $reassign;297		$post_ids = $wpdb->get_col( $wpdb->prepare( "SELECT ID FROM $wpdb->posts WHERE post_author = %d", $user_id ) );298		$link_ids = $wpdb->get_col( $wpdb->prepare( "SELECT link_id FROM $wpdb->links WHERE link_owner = %d", $user_id ) );299 300		if ( ! empty( $post_ids ) ) {301			$wpdb->query( $wpdb->prepare( "UPDATE $wpdb->posts SET post_author = %d WHERE post_author = %d", $reassign, $user_id ) );302			array_walk( $post_ids, 'clean_post_cache' );303		}304 305		if ( ! empty( $link_ids ) ) {306			$wpdb->query( $wpdb->prepare( "UPDATE $wpdb->links SET link_owner = %d WHERE link_owner = %d", $reassign, $user_id ) );307			array_walk( $link_ids, 'clean_bookmark_cache' );308		}309	}310 311	clean_user_cache( $user_id );312	restore_current_blog();313 314	return true;315}

Changelog

Introduced in MU (3.0.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 6.8.8 tag, from src/wp-includes/ms-functions.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.