add_user_to_blog

The timeline below displays how wordpress function add_user_to_blog has changed across different WordPress versions. If a version is not listed, refer to the next available version below.

WordPress Version: 6.2

/**
 * Adds a user to a blog, along with specifying the user's role.
 *
 * Use the {@see 'add_user_to_blog'} action to fire an event when users are added to a blog.
 *
 * @since MU (3.0.0)
 *
 * @param int    $blog_id ID of the blog the user is being added to.
 * @param int    $user_id ID of the user being added.
 * @param string $role    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.
 */
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;
}

WordPress Version: 5.5

/**
 * Adds a user to a blog, along with specifying the user's role.
 *
 * Use the {@see 'add_user_to_blog'} action to fire an event when users are added to a blog.
 *
 * @since MU (3.0.0)
 *
 * @param int    $blog_id ID of the blog the user is being added to.
 * @param int    $user_id ID of the user being added.
 * @param string $role    The role you want the user to have.
 * @return true|WP_Error True on success or a WP_Error object if the user doesn't exist
 *                       or could not be added.
 */
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;
}

WordPress Version: 5.4

/**
 * Adds a user to a blog.
 *
 * Use the {@see 'add_user_to_blog'} action to fire an event when users are added to a blog.
 *
 * @since MU (3.0.0)
 *
 * @param int    $blog_id ID of the blog the user is being added to.
 * @param int    $user_id ID of the user being added.
 * @param string $role    The role you want the user to have
 * @return true|WP_Error True on success or a WP_Error object if the user doesn't exist
 *                       or could not be added.
 */
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 bool|WP_Error $retval  True if the user should be added to the site, false
     *                               or 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;
}

WordPress Version: 5.3

/**
 * Adds a user to a blog.
 *
 * Use the {@see 'add_user_to_blog'} action to fire an event when users are added to a blog.
 *
 * @since MU (3.0.0)
 *
 * @param int    $blog_id ID of the blog you're adding the user to.
 * @param int    $user_id ID of the user you're adding.
 * @param string $role    The role you want the user to have
 * @return true|WP_Error
 */
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 bool|WP_Error $retval  True if the user should be added to the site, false
     *                               or 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;
}

WordPress Version: 4.9

/**
 * Adds a user to a blog.
 *
 * Use the {@see 'add_user_to_blog'} action to fire an event when users are added to a blog.
 *
 * @since MU (3.0.0)
 *
 * @param int    $blog_id ID of the blog you're adding the user to.
 * @param int    $user_id ID of the user you're adding.
 * @param string $role    The role you want the user to have
 * @return true|WP_Error
 */
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 bool|WP_Error $retval  True if the user should be added to the site, false
     *                               or 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);
    wp_cache_delete($user_id, 'users');
    wp_cache_delete($blog_id . '_user_count', 'blog-details');
    restore_current_blog();
    return true;
}

WordPress Version: 4.7

/**
 * Adds a user to a blog.
 *
 * Use the {@see 'add_user_to_blog'} action to fire an event when users are added to a blog.
 *
 * @since MU 1.0
 *
 * @param int    $blog_id ID of the blog you're adding the user to.
 * @param int    $user_id ID of the user you're adding.
 * @param string $role    The role you want the user to have
 * @return true|WP_Error
 */
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.'));
    }
    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
     *
     * @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);
    wp_cache_delete($user_id, 'users');
    wp_cache_delete($blog_id . '_user_count', 'blog-details');
    restore_current_blog();
    return true;
}

WordPress Version: 4.6

/**
 * Adds a user to a blog.
 *
 * Use the {@see 'add_user_to_blog'} action to fire an event when users are added to a blog.
 *
 * @since MU 1.0
 *
 * @param int    $blog_id ID of the blog you're adding the user to.
 * @param int    $user_id ID of the user you're adding.
 * @param string $role    The role you want the user to have
 * @return true|WP_Error
 */
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.'));
    }
    if (!get_user_meta($user_id, 'primary_blog', true)) {
        update_user_meta($user_id, 'primary_blog', $blog_id);
        $details = get_blog_details($blog_id);
        update_user_meta($user_id, 'source_domain', $details->domain);
    }
    $user->set_role($role);
    /**
     * Fires immediately after a user is added to a site.
     *
     * @since MU
     *
     * @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);
    wp_cache_delete($user_id, 'users');
    wp_cache_delete($blog_id . '_user_count', 'blog-details');
    restore_current_blog();
    return true;
}

WordPress Version: 4.3

/**
 * Add a user to a blog.
 *
 * Use the 'add_user_to_blog' action to fire an event when
 * users are added to a blog.
 *
 * @since MU 1.0
 *
 * @param int    $blog_id ID of the blog you're adding the user to.
 * @param int    $user_id ID of the user you're adding.
 * @param string $role    The role you want the user to have
 * @return true|WP_Error
 */
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.'));
    }
    if (!get_user_meta($user_id, 'primary_blog', true)) {
        update_user_meta($user_id, 'primary_blog', $blog_id);
        $details = get_blog_details($blog_id);
        update_user_meta($user_id, 'source_domain', $details->domain);
    }
    $user->set_role($role);
    /**
     * Fires immediately after a user is added to a site.
     *
     * @since MU
     *
     * @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);
    wp_cache_delete($user_id, 'users');
    wp_cache_delete($blog_id . '_user_count', 'blog-details');
    restore_current_blog();
    return true;
}

WordPress Version: 3.8

/**
 * Add a user to a blog.
 *
 * Use the 'add_user_to_blog' action to fire an event when
 * users are added to a blog.
 *
 * @since MU 1.0
 *
 * @param int $blog_id ID of the blog you're adding the user to.
 * @param int $user_id ID of the user you're adding.
 * @param string $role The role you want the user to have
 * @return bool
 */
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.'));
    }
    if (!get_user_meta($user_id, 'primary_blog', true)) {
        update_user_meta($user_id, 'primary_blog', $blog_id);
        $details = get_blog_details($blog_id);
        update_user_meta($user_id, 'source_domain', $details->domain);
    }
    $user->set_role($role);
    /**
     * Fires immediately after a user is added to a site.
     *
     * @since MU
     *
     * @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);
    wp_cache_delete($user_id, 'users');
    restore_current_blog();
    return true;
}

WordPress Version: 3.7

/**
 * Add a user to a blog.
 *
 * Use the 'add_user_to_blog' action to fire an event when
 * users are added to a blog.
 *
 * @since MU 1.0
 *
 * @param int $blog_id ID of the blog you're adding the user to.
 * @param int $user_id ID of the user you're adding.
 * @param string $role The role you want the user to have
 * @return bool
 */
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.'));
    }
    if (!get_user_meta($user_id, 'primary_blog', true)) {
        update_user_meta($user_id, 'primary_blog', $blog_id);
        $details = get_blog_details($blog_id);
        update_user_meta($user_id, 'source_domain', $details->domain);
    }
    $user->set_role($role);
    do_action('add_user_to_blog', $user_id, $role, $blog_id);
    wp_cache_delete($user_id, 'users');
    restore_current_blog();
    return true;
}