add_user_to_blog( int $blog_id, int $user_id, string $role ): true|WP_Error
Adds a user to a blog, along with specifying the user’s role.
Contents
Description
Use the ‘add_user_to_blog’ action to fire an event when users are added to a blog.
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.
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
File: wp-includes/ms-functions.php
.
View all references
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;
}
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.
Changelog
Version | Description |
---|---|
MU (3.0.0) | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
Example