* Multisite WordPress API
* Gets the network's site and user counts.
* Site and user count for the network.
* @type int $blogs Number of sites on the network.
* @type int $users Number of users on the network.
function get_sitestats() {
'blogs' => get_blog_count(),
'users' => get_user_count(),
* Get one of a user's active blogs
* Returns the user's primary blog, if they have one and
* it is active. If it's inactive, function returns another
* active blog of the user. If none are found, the user
* is added as a Subscriber to the Dashboard Blog and that blog
* @param int $user_id The unique ID of the user
* @return WP_Site|void The blog object
function get_active_blog_for_user( $user_id ) {
$blogs = get_blogs_of_user( $user_id );
if ( ! is_multisite() ) {
return $blogs[ get_current_blog_id() ];
$primary_blog = get_user_meta( $user_id, 'primary_blog', true );
$first_blog = current( $blogs );
if ( false !== $primary_blog ) {
if ( ! isset( $blogs[ $primary_blog ] ) ) {
update_user_meta( $user_id, 'primary_blog', $first_blog->userblog_id );
$primary = get_site( $first_blog->userblog_id );
$primary = get_site( $primary_blog );
// TODO: Review this call to add_user_to_blog too - to get here the user must have a role on this blog?
$result = add_user_to_blog( $first_blog->userblog_id, $user_id, 'subscriber' );
if ( ! is_wp_error( $result ) ) {
update_user_meta( $user_id, 'primary_blog', $first_blog->userblog_id );
if ( ( ! is_object( $primary ) ) || ( 1 == $primary->archived || 1 == $primary->spam || 1 == $primary->deleted ) ) {
$blogs = get_blogs_of_user( $user_id, true ); // If a user's primary blog is shut down, check their other blogs.
if ( is_array( $blogs ) && count( $blogs ) > 0 ) {
foreach ( (array) $blogs as $blog_id => $blog ) {
if ( get_current_network_id() != $blog->site_id ) {
$details = get_site( $blog_id );
if ( is_object( $details ) && 0 == $details->archived && 0 == $details->spam && 0 == $details->deleted ) {
if ( get_user_meta( $user_id, 'primary_blog', true ) != $blog_id ) {
update_user_meta( $user_id, 'primary_blog', $blog_id );
if ( ! get_user_meta( $user_id, 'source_domain', true ) ) {
update_user_meta( $user_id, 'source_domain', $details->domain );
* The number of active users in your installation.
* The count is cached and updated twice daily. This is not a live count.
* @since 4.8.0 The `$network_id` parameter has been added.
* @param int|null $network_id ID of the network. Default is the current network.
* @return int Number of active users on the network.
function get_user_count( $network_id = null ) {
return get_network_option( $network_id, 'user_count' );
* The number of active sites on your installation.
* The count is cached and updated twice daily. This is not a live count.
* @since 3.7.0 The `$network_id` parameter has been deprecated.
* @since 4.8.0 The `$network_id` parameter is now being used.
* @param int|null $network_id ID of the network. Default is the current network.
* @return int Number of active sites on the network.
function get_blog_count( $network_id = null ) {
return get_network_option( $network_id, 'blog_count' );
* Gets a blog post from any site on the network.
* This function is similar to get_post(), except that it can retrieve a post
* from any site on the network, not just the current site.
* @param int $blog_id ID of the blog.
* @param int $post_id ID of the post being looked for.
* @return WP_Post|null WP_Post object on success, null on failure
function get_blog_post( $blog_id, $post_id ) {
switch_to_blog( $blog_id );
$post = get_post( $post_id );
* 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.
* @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
function add_user_to_blog( $blog_id, $user_id, $role ) {
switch_to_blog( $blog_id );
$user = get_userdata( $user_id );
return new WP_Error( 'user_does_not_exist', __( 'The requested user does not exist.' ) );
* Filters whether a user should be added to a site.
* @param true|WP_Error $retval True if the user should be added to the site, error
* @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 ) {
if ( is_wp_error( $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.
* @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' );
* Remove a user from a blog.
* Use the {@see 'remove_user_from_blog'} action to fire an event when
* users are removed from a blog.
* Accepts an optional `$reassign` parameter, if you want to
* reassign the user's blog posts to another user upon removal.
* @global wpdb $wpdb WordPress database abstraction object.
* @param int $user_id ID of the user being removed.
* @param int $blog_id Optional. ID of the blog the user is being removed from. Default 0.
* @param int $reassign Optional. ID of the user to whom to reassign posts. Default 0.
* @return true|WP_Error True on success or a WP_Error object if the user doesn't exist.
function remove_user_from_blog( $user_id, $blog_id = 0, $reassign = 0 ) {
switch_to_blog( $blog_id );
$user_id = (int) $user_id;
* Fires before a user is removed from a site.
* @since 5.4.0 Added the `$reassign` parameter.
* @param int $user_id ID of the user being removed.
* @param int $blog_id ID of the blog the user is being removed from.
* @param int $reassign ID of the user to whom to reassign posts.
do_action( 'remove_user_from_blog', $user_id, $blog_id, $reassign );
// If being removed from the primary blog, set a new primary
// if the user is assigned to multiple blogs.
$primary_blog = get_user_meta( $user_id, 'primary_blog', true );
if ( $primary_blog == $blog_id ) {
$blogs = get_blogs_of_user( $user_id );
foreach ( (array) $blogs as $blog ) {
if ( $blog->userblog_id == $blog_id ) {
$new_id = $blog->userblog_id;
$new_domain = $blog->domain;
update_user_meta( $user_id, 'primary_blog', $new_id );
update_user_meta( $user_id, 'source_domain', $new_domain );
// wp_revoke_user( $user_id );
$user = get_userdata( $user_id );
return new WP_Error( 'user_does_not_exist', __( 'That user does not exist.' ) );
$user->remove_all_caps();
$blogs = get_blogs_of_user( $user_id );
if ( count( $blogs ) == 0 ) {
update_user_meta( $user_id, 'primary_blog', '' );
update_user_meta( $user_id, 'source_domain', '' );
$reassign = (int) $reassign;
$post_ids = $wpdb->get_col( $wpdb->prepare( "SELECT ID FROM $wpdb->posts WHERE post_author = %d", $user_id ) );
$link_ids = $wpdb->get_col( $wpdb->prepare( "SELECT link_id FROM $wpdb->links WHERE link_owner = %d", $user_id ) );
if ( ! empty( $post_ids ) ) {
$wpdb->query( $wpdb->prepare( "UPDATE $wpdb->posts SET post_author = %d WHERE post_author = %d", $reassign, $user_id ) );
array_walk( $post_ids, 'clean_post_cache' );
if ( ! empty( $link_ids ) ) {
$wpdb->query( $wpdb->prepare( "UPDATE $wpdb->links SET link_owner = %d WHERE link_owner = %d", $reassign, $user_id ) );
array_walk( $link_ids, 'clean_bookmark_cache' );
* Get the permalink for a post on another blog.
* @param int $blog_id ID of the source blog.
* @param int $post_id ID of the desired post.
* @return string The post's permalink
function get_blog_permalink( $blog_id, $post_id ) {
switch_to_blog( $blog_id );
$link = get_permalink( $post_id );
* Get a blog's numeric ID from its URL.
* On a subdirectory installation like example.com/blog1/,
* $domain will be the root 'example.com' and $path the
* subdirectory '/blog1/'. With subdomains like blog1.example.com,
* $domain is 'blog1.example.com' and $path is '/'.
* @global wpdb $wpdb WordPress database abstraction object.
* @param string $path Optional. Not required for subdomain installations.
* @return int 0 if no blog found, otherwise the ID of the matching blog
function get_blog_id_from_url( $domain, $path = '/' ) {
$domain = strtolower( $domain );
$path = strtolower( $path );
$id = wp_cache_get( md5( $domain . $path ), 'blog-id-cache' );
if ( -1 == $id ) { // Blog does not exist.
'update_site_meta_cache' => false,
$result = get_sites( $args );
$id = array_shift( $result );
wp_cache_set( md5( $domain . $path ), -1, 'blog-id-cache' );
wp_cache_set( md5( $domain . $path ), $id, 'blog-id-cache' );
* Checks an email address against a list of banned domains.
* This function checks against the Banned Email Domains list
* at wp-admin/network/settings.php. The check is only run on
* self-registrations; user creation at wp-admin/network/users.php
* @param string $user_email The email provided by the user at registration.
* @return bool True when the email address is banned, false otherwise.
function is_email_address_unsafe( $user_email ) {
$banned_names = get_site_option( 'banned_email_domains' );
if ( $banned_names && ! is_array( $banned_names ) ) {
$banned_names = explode( "\n", $banned_names );
$is_email_address_unsafe = false;
if ( $banned_names && is_array( $banned_names ) && false !== strpos( $user_email, '@', 1 ) ) {
$banned_names = array_map( 'strtolower', $banned_names );
$normalized_email = strtolower( $user_email );
list( $email_local_part, $email_domain ) = explode( '@', $normalized_email );
foreach ( $banned_names as $banned_domain ) {
if ( ! $banned_domain ) {
if ( $email_domain == $banned_domain ) {
$is_email_address_unsafe = true;
$dotted_domain = ".$banned_domain";
if ( substr( $normalized_email, -strlen( $dotted_domain ) ) === $dotted_domain ) {
$is_email_address_unsafe = true;
* Filters whether an email address is unsafe.
* @param bool $is_email_address_unsafe Whether the email address is "unsafe". Default false.
* @param string $user_email User email address.
return apply_filters( 'is_email_address_unsafe', $is_email_address_unsafe, $user_email );
* Sanitize and validate data required for a user sign-up.
* Verifies the validity and uniqueness of user names and user email addresses,
* and checks email addresses against allowed and disallowed domains provided by
* The {@see 'wpmu_validate_user_signup'} hook provides an easy way to modify the sign-up
* process. The value $result, which is passed to the hook, contains both the user-provided
* info and the error messages created by the function. {@see 'wpmu_validate_user_signup'}
* allows you to process the data in any way you'd like, and unset the relevant errors if
* @global wpdb $wpdb WordPress database abstraction object.
* @param string $user_name The login name provided by the user.
* @param string $user_email The email provided by the user.
* The array of user name, email, and the error messages.
* @type string $user_name Sanitized and unique username.
* @type string $orig_username Original username.
* @type string $user_email User email address.
* @type WP_Error $errors WP_Error object containing any errors found.
function wpmu_validate_user_signup( $user_name, $user_email ) {
$errors = new WP_Error();
$orig_username = $user_name;
$user_name = preg_replace( '/\s+/', '', sanitize_user( $user_name, true ) );
if ( $user_name != $orig_username || preg_match( '/[^a-z0-9]/', $user_name ) ) {
$errors->add( 'user_name', __( 'Usernames can only contain lowercase letters (a-z) and numbers.' ) );
$user_name = $orig_username;
$user_email = sanitize_email( $user_email );
if ( empty( $user_name ) ) {
$errors->add( 'user_name', __( 'Please enter a username.' ) );
$illegal_names = get_site_option( 'illegal_names' );
if ( ! is_array( $illegal_names ) ) {
$illegal_names = array( 'www', 'web', 'root', 'admin', 'main', 'invite', 'administrator' );
add_site_option( 'illegal_names', $illegal_names );
if ( in_array( $user_name, $illegal_names, true ) ) {
$errors->add( 'user_name', __( 'Sorry, that username is not allowed.' ) );
/** This filter is documented in wp-includes/user.php */
$illegal_logins = (array) apply_filters( 'illegal_user_logins', array() );
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
