<?php
/**
* Core User API
*
* @package WordPress
* @subpackage Users
*/
/**
* Authenticates and logs a user in with 'remember' capability.
*
* The credentials is an array that has 'user_login', 'user_password', and
* 'remember' indices. If the credentials is not given, then the log in form
* will be assumed and used if set.
*
* The various authentication cookies will be set by this function and will be
* set for a longer period depending on if the 'remember' credential is set to
* true.
*
* Note: wp_signon() doesn't handle setting the current user. This means that if the
* function is called before the {@see 'init'} hook is fired, is_user_logged_in() will
* evaluate as false until that point. If is_user_logged_in() is needed in conjunction
* with wp_signon(), wp_set_current_user() should be called explicitly.
*
* @since 2.5.0
*
* @global string $auth_secure_cookie
*
* @param array $credentials {
* Optional. User info in order to sign on.
*
* @type string $user_login Username.
* @type string $user_password User password.
* @type bool $remember Whether to 'remember' the user. Increases the time
* that the cookie will be kept. Default false.
* }
* @param string|bool $secure_cookie Optional. Whether to use secure cookie.
* @return WP_User|WP_Error WP_User on success, WP_Error on failure.
*/
function wp_signon( $credentials = array(), $secure_cookie = '' ) {
if ( empty( $credentials ) ) {
$credentials = array(
'user_login' => '',
'user_password' => '',
'remember' => false,
);
if ( ! empty( $_POST['log'] ) ) {
$credentials['user_login'] = wp_unslash( $_POST['log'] );
}
if ( ! empty( $_POST['pwd'] ) ) {
$credentials['user_password'] = $_POST['pwd'];
}
if ( ! empty( $_POST['rememberme'] ) ) {
$credentials['remember'] = $_POST['rememberme'];
}
}
if ( ! empty( $credentials['remember'] ) ) {
$credentials['remember'] = true;
} else {
$credentials['remember'] = false;
}
/**
* Fires before the user is authenticated.
*
* The variables passed to the callbacks are passed by reference,
* and can be modified by callback functions.
*
* @since 1.5.1
*
* @todo Decide whether to deprecate the wp_authenticate action.
*
* @param string $user_login Username (passed by reference).
* @param string $user_password User password (passed by reference).
*/
do_action_ref_array( 'wp_authenticate', array( &$credentials['user_login'], &$credentials['user_password'] ) );
if ( '' === $secure_cookie ) {
$secure_cookie = is_ssl();
}
/**
* Filters whether to use a secure sign-on cookie.
*
* @since 3.1.0
*
* @param bool $secure_cookie Whether to use a secure sign-on cookie.
* @param array $credentials {
* Array of entered sign-on data.
*
* @type string $user_login Username.
* @type string $user_password Password entered.
* @type bool $remember Whether to 'remember' the user. Increases the time
* that the cookie will be kept. Default false.
* }
*/
$secure_cookie = apply_filters( 'secure_signon_cookie', $secure_cookie, $credentials );
global $auth_secure_cookie; // XXX ugly hack to pass this to wp_authenticate_cookie().
$auth_secure_cookie = $secure_cookie;
add_filter( 'authenticate', 'wp_authenticate_cookie', 30, 3 );
$user = wp_authenticate( $credentials['user_login'], $credentials['user_password'] );
if ( is_wp_error( $user ) ) {
return $user;
}
wp_set_auth_cookie( $user->ID, $credentials['remember'], $secure_cookie );
/**
* Fires after the user has successfully logged in.
*
* @since 1.5.0
*
* @param string $user_login Username.
* @param WP_User $user WP_User object of the logged-in user.
*/
do_action( 'wp_login', $user->user_login, $user );
return $user;
}
/**
* Authenticates a user, confirming the username and password are valid.
*
* @since 2.8.0
*
* @param WP_User|WP_Error|null $user WP_User or WP_Error object from a previous callback. Default null.
* @param string $username Username for authentication.
* @param string $password Password for authentication.
* @return WP_User|WP_Error WP_User on success, WP_Error on failure.
*/
function wp_authenticate_username_password( $user, $username, $password ) {
if ( $user instanceof WP_User ) {
return $user;
}
if ( empty( $username ) || empty( $password ) ) {
if ( is_wp_error( $user ) ) {
return $user;
}
$error = new WP_Error();
if ( empty( $username ) ) {
$error->add( 'empty_username', __( '<strong>Error:</strong> The username field is empty.' ) );
}
if ( empty( $password ) ) {
$error->add( 'empty_password', __( '<strong>Error:</strong> The password field is empty.' ) );
}
return $error;
}
$user = get_user_by( 'login', $username );
if ( ! $user ) {
return new WP_Error(
'invalid_username',
sprintf(
/* translators: %s: User name. */
__( '<strong>Error:</strong> The username <strong>%s</strong> is not registered on this site. If you are unsure of your username, try your email address instead.' ),
$username
)
);
}
/**
* Filters whether the given user can be authenticated with the provided password.
*
* @since 2.5.0
*
* @param WP_User|WP_Error $user WP_User or WP_Error object if a previous
* callback failed authentication.
* @param string $password Password to check against the user.
*/
$user = apply_filters( 'wp_authenticate_user', $user, $password );
if ( is_wp_error( $user ) ) {
return $user;
}
if ( ! wp_check_password( $password, $user->user_pass, $user->ID ) ) {
return new WP_Error(
'incorrect_password',
sprintf(
/* translators: %s: User name. */
__( '<strong>Error:</strong> The password you entered for the username %s is incorrect.' ),
'<strong>' . $username . '</strong>'
) .
' <a href="' . wp_lostpassword_url() . '">' .
__( 'Lost your password?' ) .
'</a>'
);
}
return $user;
}
/**
* Authenticates a user using the email and password.
*
* @since 4.5.0
*
* @param WP_User|WP_Error|null $user WP_User or WP_Error object if a previous
* callback failed authentication.
* @param string $email Email address for authentication.
* @param string $password Password for authentication.
* @return WP_User|WP_Error WP_User on success, WP_Error on failure.
*/
function wp_authenticate_email_password( $user, $email, $password ) {
if ( $user instanceof WP_User ) {
return $user;
}
if ( empty( $email ) || empty( $password ) ) {
if ( is_wp_error( $user ) ) {
return $user;
}
$error = new WP_Error();
if ( empty( $email ) ) {
// Uses 'empty_username' for back-compat with wp_signon().
$error->add( 'empty_username', __( '<strong>Error:</strong> The email field is empty.' ) );
}
if ( empty( $password ) ) {
$error->add( 'empty_password', __( '<strong>Error:</strong> The password field is empty.' ) );
}
return $error;
}
if ( ! is_email( $email ) ) {
return $user;
}
$user = get_user_by( 'email', $email );
if ( ! $user ) {
return new WP_Error(
'invalid_email',
__( 'Unknown email address. Check again or try your username.' )
);
}
/** This filter is documented in wp-includes/user.php */
$user = apply_filters( 'wp_authenticate_user', $user, $password );
if ( is_wp_error( $user ) ) {
return $user;
}
if ( ! wp_check_password( $password, $user->user_pass, $user->ID ) ) {
return new WP_Error(
'incorrect_password',
sprintf(
/* translators: %s: Email address. */
__( '<strong>Error:</strong> The password you entered for the email address %s is incorrect.' ),
'<strong>' . $email . '</strong>'
) .
' <a href="' . wp_lostpassword_url() . '">' .
__( 'Lost your password?' ) .
'</a>'
);
}
return $user;
}
/**
* Authenticates the user using the WordPress auth cookie.
*
* @since 2.8.0
*
* @global string $auth_secure_cookie
*
* @param WP_User|WP_Error|null $user WP_User or WP_Error object from a previous callback. Default null.
* @param string $username Username. If not empty, cancels the cookie authentication.
* @param string $password Password. If not empty, cancels the cookie authentication.
* @return WP_User|WP_Error WP_User on success, WP_Error on failure.
*/
function wp_authenticate_cookie( $user, $username, $password ) {
if ( $user instanceof WP_User ) {
return $user;
}
if ( empty( $username ) && empty( $password ) ) {
$user_id = wp_validate_auth_cookie();
if ( $user_id ) {
return new WP_User( $user_id );
}
global $auth_secure_cookie;
if ( $auth_secure_cookie ) {
$auth_cookie = SECURE_AUTH_COOKIE;
} else {
$auth_cookie = AUTH_COOKIE;
}
if ( ! empty( $_COOKIE[ $auth_cookie ] ) ) {
return new WP_Error( 'expired_session', __( 'Please log in again.' ) );
}
// If the cookie is not set, be silent.
}
return $user;
}
/**
* Authenticates the user using an application password.
*
* @since 5.6.0
*
* @param WP_User|WP_Error|null $input_user WP_User or WP_Error object if a previous
* callback failed authentication.
* @param string $username Username for authentication.
* @param string $password Password for authentication.
* @return WP_User|WP_Error|null WP_User on success, WP_Error on failure, null if
* null is passed in and this isn't an API request.
*/
function wp_authenticate_application_password( $input_user, $username, $password ) {
if ( $input_user instanceof WP_User ) {
return $input_user;
}
if ( ! WP_Application_Passwords::is_in_use() ) {
return $input_user;
}
// The 'REST_REQUEST' check here may happen too early for the constant to be available.
$is_api_request = ( ( defined( 'XMLRPC_REQUEST' ) && XMLRPC_REQUEST ) || ( defined( 'REST_REQUEST' ) && REST_REQUEST ) );
/**
* Filters whether this is an API request that Application Passwords can be used on.
*
* By default, Application Passwords is available for the REST API and XML-RPC.
*
* @since 5.6.0
*
* @param bool $is_api_request If this is an acceptable API request.
*/
$is_api_request = apply_filters( 'application_password_is_api_request', $is_api_request );
if ( ! $is_api_request ) {
return $input_user;
}
$error = null;
$user = get_user_by( 'login', $username );
if ( ! $user && is_email( $username ) ) {
$user = get_user_by( 'email', $username );
}
// If the login name is invalid, short circuit.
if ( ! $user ) {
if ( is_email( $username ) ) {
$error = new WP_Error(
'invalid_email',
__( '<strong>Error:</strong> Unknown email address. Check again or try your username.' )
);
} else {
$error = new WP_Error(
'invalid_username',
__( '<strong>Error:</strong> Unknown username. Check again or try your email address.' )
);
}
} elseif ( ! wp_is_application_passwords_available() ) {
$error = new WP_Error(
'application_passwords_disabled',
__( 'Application passwords are not available.' )
);
} elseif ( ! wp_is_application_passwords_available_for_user( $user ) ) {
$error = new WP_Error(
'application_passwords_disabled_for_user',
__( 'Application passwords are not available for your account. Please contact the site administrator for assistance.' )
);
}
if ( $error ) {
/**
* Fires when an application password failed to authenticate the user.
*
* @since 5.6.0
*
* @param WP_Error $error The authentication error.
*/
do_action( 'application_password_failed_authentication', $error );
return $error;
}
/*
* Strips out anything non-alphanumeric. This is so passwords can be used with
* or without spaces to indicate the groupings for readability.
*
* Generated application passwords are exclusively alphanumeric.
*/
$password = preg_replace( '/[^a-z\d]/i', '', $password );
$hashed_passwords = WP_Application_Passwords::get_user_application_passwords( $user->ID );
foreach ( $hashed_passwords as $key => $item ) {
if ( ! wp_check_password( $password, $item['password'], $user->ID ) ) {
continue;
}
$error = new WP_Error();
/**
* Fires when an application password has been successfully checked as valid.
*
* This allows for plugins to add additional constraints to prevent an application password from being used.
*
* @since 5.6.0
*
* @param WP_Error $error The error object.
* @param WP_User $user The user authenticating.
* @param array $item The details about the application password.
* @param string $password The raw supplied password.
*/
do_action( 'wp_authenticate_application_password_errors', $error, $user, $item, $password );
if ( is_wp_error( $error ) && $error->has_errors() ) {
/** This action is documented in wp-includes/user.php */
do_action( 'application_password_failed_authentication', $error );
return $error;
}
WP_Application_Passwords::record_application_password_usage( $user->ID, $item['uuid'] );
/**
* Fires after an application password was used for authentication.
*
* @since 5.6.0
*
* @param WP_User $user The user who was authenticated.
* @param array $item The application password used.
*/
do_action( 'application_password_did_authenticate', $user, $item );
return $user;
}
$error = new WP_Error(
'incorrect_password',
__( 'The provided password is an invalid application password.' )
);
/** This action is documented in wp-includes/user.php */
do_action( 'application_password_failed_authentication', $error );
return $error;
}
/**
* Validates the application password credentials passed via Basic Authentication.
*
* @since 5.6.0
*
* @param int|false $input_user User ID if one has been determined, false otherwise.
* @return int|false The authenticated user ID if successful, false otherwise.
*/
function wp_validate_application_password( $input_user ) {
// Don't authenticate twice.
if ( ! empty( $input_user ) ) {
return $input_user;
}
if ( ! wp_is_application_passwords_available() ) {
return $input_user;
}
// Both $_SERVER['PHP_AUTH_USER'] and $_SERVER['PHP_AUTH_PW'] must be set in order to attempt authentication.
if ( ! isset( $_SERVER['PHP_AUTH_USER'], $_SERVER['PHP_AUTH_PW'] ) ) {
return $input_user;
}
$authenticated = wp_authenticate_application_password( null, $_SERVER['PHP_AUTH_USER'], $_SERVER['PHP_AUTH_PW'] );
if ( $authenticated instanceof WP_User ) {
return $authenticated->ID;
}
// If it wasn't a user what got returned, just pass on what we had received originally.
return $input_user;
}
/**
* For Multisite blogs, checks if the authenticated user has been marked as a
* spammer, or if the user's primary blog has been marked as spam.
*
* @since 3.7.0
*
* @param WP_User|WP_Error|null $user WP_User or WP_Error object from a previous callback. Default null.
* @return WP_User|WP_Error WP_User on success, WP_Error if the user is considered a spammer.
*/
function wp_authenticate_spam_check( $user ) {
if ( $user instanceof WP_User && is_multisite() ) {
/**
* Filters whether the user has been marked as a spammer.
*
* @since 3.7.0
*
* @param bool $spammed Whether the user is considered a spammer.
* @param WP_User $user User to check against.
*/
$spammed = apply_filters( 'check_is_user_spammed', is_user_spammy( $user ), $user );
if ( $spammed ) {
return new WP_Error( 'spammer_account', __( '<strong>Error:</strong> Your account has been marked as a spammer.' ) );
}
}
return $user;
}
/**
* Validates the logged-in cookie.
*
* Checks the logged-in cookie if the previous auth cookie could not be
* validated and parsed.
*
* This is a callback for the {@see 'determine_current_user'} filter, rather than API.
*
* @since 3.9.0
*
* @param int|false $user_id The user ID (or false) as received from
* the `determine_current_user` filter.
* @return int|false User ID if validated, false otherwise. If a user ID from
* an earlier filter callback is received, that value is returned.
*/
function wp_validate_logged_in_cookie( $user_id ) {
if ( $user_id ) {
return $user_id;
}
if ( is_blog_admin() || is_network_admin() || empty( $_COOKIE[ LOGGED_IN_COOKIE ] ) ) {
return false;
}
return wp_validate_auth_cookie( $_COOKIE[ LOGGED_IN_COOKIE ], 'logged_in' );
}
/**
* Gets the number of posts a user has written.
*
* @since 3.0.0
* @since 4.1.0 Added `$post_type` argument.
* @since 4.3.0 Added `$public_only` argument. Added the ability to pass an array
* of post types to `$post_type`.
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int $userid User ID.
* @param array|string $post_type Optional. Single post type or array of post types to count the number of posts for. Default 'post'.
* @param bool $public_only Optional. Whether to only return counts for public posts. Default false.
* @return string Number of posts the user has written in this post type.
*/
function count_user_posts( $userid, $post_type = 'post', $public_only = false ) {
global $wpdb;
$where = get_posts_by_author_sql( $post_type, true, $userid, $public_only );
$count = $wpdb->get_var( "SELECT COUNT(*) FROM $wpdb->posts $where" );
/**
* Filters the number of posts a user has written.
*
* @since 2.7.0
* @since 4.1.0 Added `$post_type` argument.
* @since 4.3.1 Added `$public_only` argument.
*
* @param int $count The user's post count.
* @param int $userid User ID.
* @param string|array $post_type Single post type or array of post types to count the number of posts for.
* @param bool $public_only Whether to limit counted posts to public posts.
*/
return apply_filters( 'get_usernumposts', $count, $userid, $post_type, $public_only );
}
/**
* Gets the number of posts written by a list of users.
*
* @since 3.0.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int[] $users Array of user IDs.
* @param string|string[] $post_type Optional. Single post type or array of post types to check. Defaults to 'post'.
* @param bool $public_only Optional. Only return counts for public posts. Defaults to false.
* @return string[] Amount of posts each user has written, as strings, keyed by user ID.
*/
function count_many_users_posts( $users, $post_type = 'post', $public_only = false ) {
global $wpdb;
$count = array();
if ( empty( $users ) || ! is_array( $users ) ) {
return $count;
}
$userlist = implode( ',', array_map( 'absint', $users ) );
$where = get_posts_by_author_sql( $post_type, true, null, $public_only );
$result = $wpdb->get_results( "SELECT post_author, COUNT(*) FROM $wpdb->posts $where AND post_author IN ($userlist) GROUP BY post_author", ARRAY_N );
foreach ( $result as $row ) {
$count[ $row[0] ] = $row[1];
}
foreach ( $users as $id ) {
if ( ! isset( $count[ $id ] ) ) {
$count[ $id ] = 0;
}
}
return $count;
}
//
// User option functions.
//
/**
* Gets the current user's ID.
*
* @since MU (3.0.0)
*
* @return int The current user's ID, or 0 if no user is logged in.
*/
function get_current_user_id() {
if ( ! function_exists( 'wp_get_current_user' ) ) {
return 0;
}
$user = wp_get_current_user();
return ( isset( $user->ID ) ? (int) $user->ID : 0 );
}
/**
* Retrieves user option that can be either per Site or per Network.
*
* If the user ID is not given, then the current user will be used instead. If
* the user ID is given, then the user data will be retrieved. The filter for
* the result, will also pass the original option name and finally the user data
* object as the third parameter.
*
* The option will first check for the per site name and then the per Network name.
*
* @since 2.0.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param string $option User option name.
* @param int $user Optional. User ID.
* @param string $deprecated Use get_option() to check for an option in the options table.
* @return mixed User option value on success, false on failure.
*/
function get_user_option( $option, $user = 0, $deprecated = '' ) {
global $wpdb;
if ( ! empty( $deprecated ) ) {
_deprecated_argument( __FUNCTION__, '3.0.0' );
}
if ( empty( $user ) ) {
$user = get_current_user_id();
}
$user = get_userdata( $user );
if ( ! $user ) {
return false;
}
$prefix = $wpdb->get_blog_prefix();
if ( $user->has_prop( $prefix . $option ) ) { // Blog-specific.
$result = $user->get( $prefix . $option );
} elseif ( $user->has_prop( $option ) ) { // User-specific and cross-blog.
$result = $user->get( $option );
} else {
$result = false;
}
/**
* Filters a specific user option value.
*
* The dynamic portion of the hook name, `$option`, refers to the user option name.
*
* @since 2.5.0
*
* @param mixed $result Value for the user's option.
* @param string $option Name of the option being retrieved.
* @param WP_User $user WP_User object of the user whose option is being retrieved.
*/
return apply_filters( "get_user_option_{$option}", $result, $option, $user );
}
/**
* Updates user option with global blog capability.
*
* User options are just like user metadata except that they have support for
* global blog options. If the 'is_global' parameter is false, which it is by default,
* it will prepend the WordPress table prefix to the option name.
*
* Deletes the user option if $newvalue is empty.
*
* @since 2.0.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int $user_id User ID.
* @param string $option_name User option name.
* @param mixed $newvalue User option value.
* @param bool $is_global Optional. Whether option name is global or blog specific.
* Default false (blog specific).
* @return int|bool User meta ID if the option didn't exist, true on successful update,
* false on failure.
*/
function update_user_option( $user_id, $option_name, $newvalue, $is_global = false ) {
global $wpdb;
if ( ! $is_global ) {
$option_name = $wpdb->get_blog_prefix() . $option_name;
}
return update_user_meta( $user_id, $option_name, $newvalue );
}
/**
* Deletes user option with global blog capability.
*
* User options are just like user metadata except that they have support for
* global blog options. If the 'is_global' parameter is false, which it is by default,
* it will prepend the WordPress table prefix to the option name.
*
* @since 3.0.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int $user_id User ID
* @param string $option_name User option name.
* @param bool $is_global Optional. Whether option name is global or blog specific.
* Default false (blog specific).
* @return bool True on success, false on failure.
*/
function delete_user_option( $user_id, $option_name, $is_global = false ) {
global $wpdb;
if ( ! $is_global ) {
$option_name = $wpdb->get_blog_prefix() . $option_name;
}
return delete_user_meta( $user_id, $option_name );
}
/**
* Retrieves list of users matching criteria.
*
* @since 3.1.0
*
* @see WP_User_Query
*
* @param array $args Optional. Arguments to retrieve users. See WP_User_Query::prepare_query()
* for more information on accepted arguments.
* @return array List of users.
*/
function get_users( $args = array() ) {
$args = wp_parse_args( $args );
$args['count_total'] = false;
$user_search = new WP_User_Query( $args );
return (array) $user_search->get_results();
}
/**
* Lists all the users of the site, with several options available.
*
* @since 5.9.0
*
* @param string|array $args {
* Optional. Array or string of default arguments.
*
* @type string $orderby How to sort the users. Accepts 'nicename', 'email', 'url', 'registered',
* 'user_nicename', 'user_email', 'user_url', 'user_registered', 'name',
* 'display_name', 'post_count', 'ID', 'meta_value', 'user_login'. Default 'name'.
* @type string $order Sorting direction for $orderby. Accepts 'ASC', 'DESC'. Default 'ASC'.
* @type int $number Maximum users to return or display. Default empty (all users).
* @type bool $exclude_admin Whether to exclude the 'admin' account, if it exists. Default false.
* @type bool $show_fullname Whether to show the user's full name. Default false.
* @type string $feed If not empty, show a link to the user's feed and use this text as the alt
* parameter of the link. Default empty.
* @type string $feed_image If not empty, show a link to the user's feed and use this image URL as
* clickable anchor. Default empty.
* @type string $feed_type The feed type to link to, such as 'rss2'. Defaults to default feed type.
* @type bool $echo Whether to output the result or instead return it. Default true.
* @type string $style If 'list', each user is wrapped in an `<li>` element, otherwise the users
* will be separated by commas.
* @type bool $html Whether to list the items in HTML form or plaintext. Default true.
* @type string $exclude An array, comma-, or space-separated list of user IDs to exclude. Default empty.
* @type string $include An array, comma-, or space-separated list of user IDs to include. Default empty.
* }
* @return string|null The output if echo is false. Otherwise null.
*/
function wp_list_users( $args = array() ) {
$defaults = array(
'orderby' => 'name',
'order' => 'ASC',
'number' => '',
'exclude_admin' => true,
'show_fullname' => false,
'feed' => '',
'feed_image' => '',
'feed_type' => '',
'echo' => true,
'style' => 'list',
'html' => true,
'exclude' => '',
'include' => '',
);
$parsed_args = wp_parse_args( $args, $defaults );
$return = '';
$query_args = wp_array_slice_assoc( $parsed_args, array( 'orderby', 'order', 'number', 'exclude', 'include' ) );
$query_args['fields'] = 'ids';
/**
* Filters the query arguments for the list of all users of the site.
*
* @since 6.1.0
*
* @param array $query_args The query arguments for get_users().
* @param array $parsed_args The arguments passed to wp_list_users() combined with the defaults.
*/
$query_args = apply_filters( 'wp_list_users_args', $query_args, $parsed_args );
$users = get_users( $query_args );
foreach ( $users as $user_id ) {
$user = get_userdata( $user_id );
if ( $parsed_args['exclude_admin'] && 'admin' === $user->display_name ) {
continue;
}
if ( $parsed_args['show_fullname'] && '' !== $user->first_name && '' !== $user->last_name ) {
$name = sprintf(
/* translators: 1: User's first name, 2: Last name. */
_x( '%1$s %2$s', 'Display name based on first name and last name' ),
$user->first_name,
$user->last_name
);
} else {
$name = $user->display_name;
}
if ( ! $parsed_args['html'] ) {
$return .= $name . ', ';
continue; // No need to go further to process HTML.
}
if ( 'list' === $parsed_args['style'] ) {
$return .= '<li>';
}
$row = $name;
if ( ! empty( $parsed_args['feed_image'] ) || ! empty( $parsed_args['feed'] ) ) {
$row .= ' ';
if ( empty( $parsed_args['feed_image'] ) ) {
$row .= '(';
}
$row .= '<a href="' . get_author_feed_link( $user->ID, $parsed_args['feed_type'] ) . '"';
$alt = '';
if ( ! empty( $parsed_args['feed'] ) ) {
$alt = ' alt="' . esc_attr( $parsed_args['feed'] ) . '"';
$name = $parsed_args['feed'];
}
$row .= '>';
if ( ! empty( $parsed_args['feed_image'] ) ) {
$row .= '<img src="' . esc_url( $parsed_args['feed_image'] ) . '" style="border: none;"' . $alt . ' />';
} else {
$row .= $name;
}
$row .= '</a>';
if ( empty( $parsed_args['feed_image'] ) ) {
$row .= ')';
}
}
$return .= $row;
$return .= ( 'list' === $parsed_args['style'] ) ? '</li>' : ', ';
}
$return = rtrim( $return, ', ' );
if ( ! $parsed_args['echo'] ) {
return $return;
}
echo $return;
}
/**
* Gets the sites a user belongs to.
*
* @since 3.0.0
* @since 4.7.0 Converted to use `get_sites()`.
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int $user_id User ID
* @param bool $all Whether to retrieve all sites, or only sites that are not
* marked as deleted, archived, or spam.
* @return object[] A list of the user's sites. An empty array if the user doesn't exist
* or belongs to no sites.
*/
function get_blogs_of_user( $user_id, $all = false ) {
global $wpdb;
$user_id = (int) $user_id;
// Logged out users can't have sites.
if ( empty( $user_id ) ) {
return array();
}
/**
* Filters the list of a user's sites before it is populated.
*
* Returning a non-null value from the filter will effectively short circuit
* get_blogs_of_user(), returning that value instead.
*
* @since 4.6.0
*
* @param null|object[] $sites An array of site objects of which the user is a member.
* @param int $user_id User ID.
* @param bool $all Whether the returned array should contain all sites, including
* those marked 'deleted', 'archived', or 'spam'. Default false.
*/
$sites = apply_filters( 'pre_get_blogs_of_user', null, $user_id, $all );
if ( null !== $sites ) {
return $sites;
}
$keys = get_user_meta( $user_id );
if ( empty( $keys ) ) {
return array();
}
if ( ! is_multisite() ) {
$site_id = get_current_blog_id();
$sites = array( $site_id => new stdClass() );
$sites[ $site_id ]->userblog_id = $site_id;
$sites[ $site_id ]->blogname = get_option( 'blogname' );
$sites[ $site_id ]->domain = '';
$sites[ $site_id ]->path = '';
$sites[ $site_id ]->site_id = 1;
$sites[ $site_id ]->siteurl = get_option( 'siteurl' );
$sites[ $site_id ]->archived = 0;
$sites[ $site_id ]->spam = 0;
$sites[ $site_id ]->deleted = 0;
return $sites;
}
$site_ids = array();
if ( isset( $keys[ $wpdb->base_prefix . 'capabilities' ] ) && defined( 'MULTISITE' ) ) {
$site_ids[] = 1;
unset( $keys[ $wpdb->base_prefix . 'capabilities' ] );
}
$keys = array_keys( $keys );
foreach ( $keys as $key ) {
if ( ! str_ends_with( $key, 'capabilities' ) ) {
continue;
}
if ( $wpdb->base_prefix && ! str_starts_with( $key, $wpdb->base_prefix ) ) {
continue;
}
$site_id = str_replace( array( $wpdb->base_prefix, '_capabilities' ), '', $key );
if ( ! is_numeric( $site_id ) ) {
continue;
}
$site_ids[] = (int) $site_id;
}
$sites = array();
if ( ! empty( $site_ids ) ) {
$args = array(
'number' => '',
'site__in' => $site_ids,
);
if ( ! $all ) {
$args['archived'] = 0;
$args['spam'] = 0;
$args['deleted'] = 0;
}
$_sites = get_sites( $args );
foreach ( $_sites as $site ) {
$sites[ $site->id ] = (object) array(
'userblog_id' => $site->id,
'blogname' => $site->blogname,
'domain' => $site->domain,
'path' => $site->path,
'site_id' => $site->network_id,
'siteurl' => $site->siteurl,
'archived' => $site->archived,
'mature' => $site->mature,
'spam' => $site->spam,
'deleted' => $site->deleted,
);
}
}
/**
* Filters the list of sites a user belongs to.
*
* @since MU (3.0.0)
*
* @param object[] $sites An array of site objects belonging to the user.
* @param int $user_id User ID.
* @param bool $all Whether the returned sites array should contain all sites, including
* those marked 'deleted', 'archived', or 'spam'. Default false.
*/
return apply_filters( 'get_blogs_of_user', $sites, $user_id, $all );
}
/**
* Finds out whether a user is a member of a given blog.
*
* @since MU (3.0.0)
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int $user_id Optional. The unique ID of the user. Defaults to the current user.
* @param int $blog_id Optional. ID of the blog to check. Defaults to the current site.
* @return bool
*/
function is_user_member_of_blog( $user_id = 0, $blog_id = 0 ) {
global $wpdb;
$user_id = (int) $user_id;
$blog_id = (int) $blog_id;
if ( empty( $user_id ) ) {
$user_id = get_current_user_id();
}
/*
* Technically not needed, but does save calls to get_site() and get_user_meta()
* in the event that the function is called when a user isn't logged in.
*/
if ( empty( $user_id ) ) {
return false;
} else {
$user = get_userdata( $user_id );
if ( ! $user instanceof WP_User ) {
return false;
}
}
if ( ! is_multisite() ) {
return true;
}
if ( empty( $blog_id ) ) {
$blog_id = get_current_blog_id();
}
$blog = get_site( $blog_id );
if ( ! $blog || ! isset( $blog->domain ) || $blog->archived || $blog->spam || $blog->deleted ) {
return false;
}
$keys = get_user_meta( $user_id );
if ( empty( $keys ) ) {
return false;
}
// No underscore before capabilities in $base_capabilities_key.
$base_capabilities_key = $wpdb->base_prefix . 'capabilities';
$site_capabilities_key = $wpdb->base_prefix . $blog_id . '_capabilities';
if ( isset( $keys[ $base_capabilities_key ] ) && 1 == $blog_id ) {
return true;
}
if ( isset( $keys[ $site_capabilities_key ] ) ) {
return true;
}
return false;
}
/**
* Adds meta data to a user.
*
* @since 3.0.0
*
* @param int $user_id User ID.
* @param string $meta_key Metadata name.
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param bool $unique Optional. Whether the same key should not be added.
* Default false.
* @return int|false Meta ID on success, false on failure.
*/
function add_user_meta( $user_id, $meta_key, $meta_value, $unique = false ) {
return add_metadata( 'user', $user_id, $meta_key, $meta_value, $unique );
}
/**
* Removes metadata matching criteria from a user.
*
* You can match based on the key, or key and value. Removing based on key and
* value, will keep from removing duplicate metadata with the same key. It also
* allows removing all metadata matching key, if needed.
*
* @since 3.0.0
*
* @link https://developer.wordpress.org/reference/functions/delete_user_meta/
*
* @param int $user_id User ID
* @param string $meta_key Metadata name.
* @param mixed $meta_value Optional. Metadata value. If provided,
* rows will only be removed that match the value.
* Must be serializable if non-scalar. Default empty.
* @return bool True on success, false on failure.
*/
function delete_user_meta( $user_id, $meta_key, $meta_value = '' ) {
return delete_metadata( 'user', $user_id, $meta_key, $meta_value );
}
/**
* Retrieves user meta field for a user.
*
* @since 3.0.0
*
* @link https://developer.wordpress.org/reference/functions/get_user_meta/
*
* @param int $user_id User ID.
* @param string $key Optional. The meta key to retrieve. By default,
* returns data for all keys.
* @param bool $single Optional. Whether to return a single value.
* This parameter has no effect if `$key` is not specified.
* Default false.
* @return mixed An array of values if `$single` is false.
* The value of meta data field if `$single` is true.
* False for an invalid `$user_id` (non-numeric, zero, or negative value).
* An empty string if a valid but non-existing user ID is passed.
*/
function get_user_meta( $user_id, $key = '', $single = false ) {
return get_metadata( 'user', $user_id, $key, $single );
}
/**
* Updates user meta field based on user ID.
*
* Use the $prev_value parameter to differentiate between meta fields with the
* same key and user ID.
*
* If the meta field for the user does not exist, it will be added.
*
* @since 3.0.0
*
* @link https://developer.wordpress.org/reference/functions/update_user_meta/
*
* @param int $user_id User ID.
* @param string $meta_key Metadata key.
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param mixed $prev_value Optional. Previous value to check before updating.
* If specified, only update existing metadata entries with
* this value. Otherwise, update all entries. Default empty.
* @return int|bool Meta ID if the key didn't exist, true on successful update,
* false on failure or if the value passed to the function
* is the same as the one that is already in the database.
*/
function update_user_meta( $user_id, $meta_key, $meta_value, $prev_value = '' ) {
return update_metadata( 'user', $user_id, $meta_key, $meta_value, $prev_value );
}
/**
* Counts number of users who have each of the user roles.
*
* Assumes there are neither duplicated nor orphaned capabilities meta_values.
* Assumes role names are unique phrases. Same assumption made by WP_User_Query::prepare_query()
* Using $strategy = 'time' this is CPU-intensive and should handle around 10^7 users.
* Using $strategy = 'memory' this is memory-intensive and should handle around 10^5 users, but see WP Bug #12257.
*
* @since 3.0.0
* @since 4.4.0 The number of users with no role is now included in the `none` element.
* @since 4.9.0 The `$site_id` parameter was added to support multisite.
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param string $strategy Optional. The computational strategy to use when counting the users.
* Accepts either 'time' or 'memory'. Default 'time'.
* @param int|null $site_id Optional. The site ID to count users for. Defaults to the current site.
* @return array {
* User counts.
*
* @type int $total_users Total number of users on the site.
* @type int[] $avail_roles Array of user counts keyed by user role.
* }
*/
function count_users( $strategy = 'time', $site_id = null ) {
global $wpdb;
// Initialize.
if ( ! $site_id ) {
$site_id = get_current_blog_id();
}
/**
* Filters the user count before queries are run.
*
* Return a non-null value to cause count_users() to return early.
*
* @since 5.1.0
*
* @param null|array $result The value to return instead. Default null to continue with the query.
* @param string $strategy Optional. The computational strategy to use when counting the users.
* Accepts either 'time' or 'memory'. Default 'time'.
* @param int $site_id The site ID to count users for.
*/
$pre = apply_filters( 'pre_count_users', null, $strategy, $site_id );
if ( null !== $pre ) {
return $pre;
}
$blog_prefix = $wpdb->get_blog_prefix( $site_id );
$result = array();
if ( 'time' === $strategy ) {
if ( is_multisite() && get_current_blog_id() != $site_id ) {
switch_to_blog( $site_id );
$avail_roles = wp_roles()->get_names();
restore_current_blog();
} else {
$avail_roles = wp_roles()->get_names();
}
// Build a CPU-intensive query that will return concise information.
$select_count = array();
foreach ( $avail_roles as $this_role => $name ) {
$select_count[] = $wpdb->prepare( 'COUNT(NULLIF(`meta_value` LIKE %s, false))', '%' . $wpdb->esc_like( '"' . $this_role . '"' ) . '%' );
}
$select_count[] = "COUNT(NULLIF(`meta_value` = 'a:0:{}', false))";
$select_count = implode( ', ', $select_count );
// Add the meta_value index to the selection list, then run the query.
$row = $wpdb->get_row(
"
SELECT {$select_count}, COUNT(*)
FROM {$wpdb->usermeta}
INNER JOIN {$wpdb->users} ON user_id = ID
WHERE meta_key = '{$blog_prefix}capabilities'
",
ARRAY_N
);
// Run the previous loop again to associate results with role names.
$col = 0;
$role_counts = array();
foreach ( $avail_roles as $this_role => $name ) {
$count = (int) $row[ $col++ ];
if ( $count > 0 ) {
$role_counts[ $this_role ] = $count;
}
}
$role_counts['none'] = (i