add_user_to_blog() – Function | Developer.WordPress.org

Adds a user to a blog, along with specifying the user’s role.

Description

Use the ‘add_user_to_blog’ action to fire an event when users are added to a blog.

Parameters

$blog_idintrequired: ID of the blog the user is being added to.
$user_idintrequired: ID of the user being added.
$rolestringrequired: User role.

Return

true|WP_Error True on success or a WP_Error object if the user doesn’t exist or could not be added.

More Information

It does not check if the user is already a member of the blog before setting their role. If you don’t want to overwrite the role of a user if they are already a member of the blog, use is_user_member_of_blog() to check that first.
You do not need to call switch_to_blog() to switch to the blog you want to add the user to before calling this function. The function will switch to the blog itself, and restore the current blog before returning as well.

Source

function add_user_to_blog( $blog_id, $user_id, $role ) {
	switch_to_blog( $blog_id );

	$user = get_userdata( $user_id );

	if ( ! $user ) {
		restore_current_blog();
		return new WP_Error( 'user_does_not_exist', __( 'The requested user does not exist.' ) );
	}

	/**
	 * Filters whether a user should be added to a site.
	 *
	 * @since 4.9.0
	 *
	 * @param true|WP_Error $retval  True if the user should be added to the site, error
	 *                               object otherwise.
	 * @param int           $user_id User ID.
	 * @param string        $role    User role.
	 * @param int           $blog_id Site ID.
	 */
	$can_add_user = apply_filters( 'can_add_user_to_blog', true, $user_id, $role, $blog_id );

	if ( true !== $can_add_user ) {
		restore_current_blog();

		if ( is_wp_error( $can_add_user ) ) {
			return $can_add_user;
		}

		return new WP_Error( 'user_cannot_be_added', __( 'User cannot be added to this site.' ) );
	}

	if ( ! get_user_meta( $user_id, 'primary_blog', true ) ) {
		update_user_meta( $user_id, 'primary_blog', $blog_id );
		$site = get_site( $blog_id );
		update_user_meta( $user_id, 'source_domain', $site->domain );
	}

	$user->set_role( $role );

	/**
	 * Fires immediately after a user is added to a site.
	 *
	 * @since MU (3.0.0)
	 *
	 * @param int    $user_id User ID.
	 * @param string $role    User role.
	 * @param int    $blog_id Blog ID.
	 */
	do_action( 'add_user_to_blog', $user_id, $role, $blog_id );

	clean_user_cache( $user_id );
	wp_cache_delete( $blog_id . '_user_count', 'blog-details' );

	restore_current_blog();

	return true;
}

View all references View on Trac View on GitHub

Hooks

do_action( ‘add_user_to_blog’, int $user_id, string $role, int $blog_id ): Fires immediately after a user is added to a site.
apply_filters( ‘can_add_user_to_blog’, true|WP_Error $retval, int $user_id, string $role, int $blog_id ): Filters whether a user should be added to a site.

Uses	Description
get_site()`wp-includes/ms-site.php`	Retrieves site data given a site ID or site object.
wp_cache_delete()`wp-includes/cache.php`	Removes the cache contents matching key and group.
clean_user_cache()`wp-includes/user.php`	Cleans all user caches.
get_user_meta()`wp-includes/user.php`	Retrieves user meta field for a user.
update_user_meta()`wp-includes/user.php`	Updates user meta field based on user ID.
switch_to_blog()`wp-includes/ms-blogs.php`	Switches the current blog.
restore_current_blog()`wp-includes/ms-blogs.php`	Restores the current blog, after calling switch_to_blog() .
get_userdata()`wp-includes/pluggable.php`	Retrieves user info by user ID.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
do_action()`wp-includes/plugin.php`	Calls the callback functions that have been added to an action hook.
is_wp_error()`wp-includes/load.php`	Checks whether the given variable is a WordPress Error.
WP_Error::__construct()`wp-includes/class-wp-error.php`	Initializes the error.

Show 7 more Show less

Used by	Description
wp_initialize_site()`wp-includes/ms-site.php`	Runs the initialization routine for a given site.
WP_REST_Users_Controller::create_item()`wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php`	Creates a single user.
add_existing_user_to_blog()`wp-includes/ms-functions.php`	Adds a user to a blog based on details from maybe_add_existing_user_to_blog() .
add_new_user_to_blog()`wp-includes/ms-functions.php`	Adds a newly created user to the appropriate blog
get_active_blog_for_user()`wp-includes/ms-functions.php`	Gets one of a user’s active blogs.

Changelog

Version	Description
MU (3.0.0)	Introduced.

User Contributed Notes

Codex 9 years ago

-1

Example

<?php
//ADD USER ID 1 TO BLOG ID 1 AS AN EDITOR
$user_id = 1; 
$blog_id = 1;
$role = 'editor';
add_user_to_blog( $blog_id, $user_id, $role )
?>

<?php 
//ADD USER ID 2 TO BLOG ID 3 AS AN ADMINISTRATOR
$user_id = 2; 
$blog_id = 3;
$role = 'administrator';
add_user_to_blog( $blog_id, $user_id, $role )
?>

add_user_to_blog( int $blog_id, int $user_id, string $role ): true|WP_Error

In this article