add_user_to_blog( int $blog_id, int $user_id, string $role )

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

Contents

Description Description

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

Top ↑

Parameters Parameters

$blog_id

(int) (Required) ID of the blog the user is being added to.

$user_id

(int) (Required) ID of the user being added.

$role

(string) (Required) The role you want the user to have.

Top ↑

Return Return

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

Top ↑

More Information 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.

Top ↑

Source Source

File: wp-includes/ms-functions.php 

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;
}

Expand full source code Collapse full source code View on Trac

Top ↑

Uses Uses

Uses
Uses Description
wp-includes/ms-functions.php: can_add_user_to_blog

Filters whether a user should be added to a site.
wp-includes/ms-site.php: get_site()

Retrieves site data given a site ID or site object.
wp-includes/cache.php: wp_cache_delete()

Removes the cache contents matching key and group.
wp-includes/l10n.php: __()

Retrieve the translation of $text.
wp-includes/pluggable.php: get_userdata()

Retrieve user info by user ID.
wp-includes/plugin.php: apply_filters()

Calls the callback functions that have been added to a filter hook.
wp-includes/plugin.php: do_action()

Execute functions hooked on a specific action hook.
wp-includes/user.php: clean_user_cache()

Clean all user caches
wp-includes/user.php: get_user_meta()

Retrieve user meta field for a user.
wp-includes/user.php: update_user_meta()

Update user meta field based on user ID.
wp-includes/ms-functions.php: add_user_to_blog

Fires immediately after a user is added to a site.
wp-includes/ms-blogs.php: switch_to_blog()

Switch the current blog.
wp-includes/ms-blogs.php: restore_current_blog()

Restore the current blog, after calling switch_to_blog().
wp-includes/load.php: is_wp_error()

Checks whether the given variable is a WordPress Error.
wp-includes/class-wp-error.php: WP_Error::__construct()

Initializes the error.
Show 10 more uses Hide more uses

Top ↑

Used By Used By

Used By
Used By Description
wp-includes/ms-site.php: wp_initialize_site()

Runs the initialization routine for a given site.
wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php: WP_REST_Users_Controller::create_item()

Creates a single user.
wp-includes/ms-functions.php: add_existing_user_to_blog()

Add a user to a blog based on details from maybe_add_existing_user_to_blog().
wp-includes/ms-functions.php: add_new_user_to_blog()

Adds a newly created user to the appropriate blog
wp-includes/ms-functions.php: get_active_blog_for_user()

Get one of a user’s active blogs

Top ↑

Changelog Changelog

Changelog
Version Description
MU (3.0.0) Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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 )
?>

    Expand full source codeCollapse full source code

You must log in before being able to contribute a note or feedback.