*
* @since 2.5.0
*
- * @param array $credentials Optional. User info in order to sign on.
- * @param bool $secure_cookie Optional. Whether to use secure cookie.
+ * @param array $credentials Optional. User info in order to sign on.
+ * @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 = '' ) {
*
* @since 3.9.0
*
- * @param int|bool $user The user ID (or false) as received from the
+ * @param int|bool $user_id The user ID (or false) as received from the
* determine_current_user filter.
* @return int|bool User ID if validated, false otherwise. If a user ID from
* an earlier filter callback is received, that value is returned.
* Number of posts user has written.
*
* @since 3.0.0
+ * @since 4.1.0 Added `$post_type` argument.
*
* @global wpdb $wpdb WordPress database object for queries.
*
- * @param int $userid User ID.
- * @return int Amount of posts user has written.
+ * @param int $userid User ID.
+ * @param string $post_type Optional. Post type to count the number of posts for. Default 'post'.
+ * @return int Number of posts the user has written in this post type.
*/
-function count_user_posts($userid) {
+function count_user_posts( $userid, $post_type = 'post' ) {
global $wpdb;
- $where = get_posts_by_author_sql('post', true, $userid);
+ $where = get_posts_by_author_sql( $post_type, true, $userid );
$count = $wpdb->get_var( "SELECT COUNT(*) FROM $wpdb->posts $where" );
* Filter the number of posts a user has written.
*
* @since 2.7.0
+ * @since 4.1.0 Added `$post_type` argument.
*
- * @param int $count The user's post count.
- * @param int $userid User ID.
+ * @param int $count The user's post count.
+ * @param int $userid User ID.
+ * @param string $post_type Post type to count the number of posts for.
*/
- return apply_filters( 'get_usernumposts', $count, $userid );
+ return apply_filters( 'get_usernumposts', $count, $userid, $post_type );
}
/**
*
* @since MU
*
- * @uses wp_get_current_user
- *
* @return int The current user's ID
*/
function get_current_user_id() {
*
* @param string $option User option name.
* @param int $user Optional. User ID.
- * @param bool $deprecated Use get_option() to check for an option in the options table.
+ * @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 = '' ) {
/**
* Filter a specific user option value.
*
- * The dynamic portion of the hook name, $option, refers to the user option name.
+ * The dynamic portion of the hook name, `$option`, refers to the user option name.
*
* @since 2.5.0
*
* WordPress User Query class.
*
* @since 3.1.0
+ *
+ * @see WP_User_Query::prepare_query() for information on accepted arguments.
*/
class WP_User_Query {
*
* @since 3.1.0
*
- * @param string|array $args Optional. The query variables.
+ * @param null|string|array $args Optional. The query variables.
* @return WP_User_Query
*/
public function __construct( $query = null ) {
* Prepare the query variables.
*
* @since 3.1.0
+ * @access public
*
- * @param string|array $args Optional. The query variables.
+ * @param string|array $query {
+ * Optional. Array or string of Query parameters.
+ *
+ * @type int $blog_id The site ID. Default is the global blog id.
+ * @type string $role Role name. Default empty.
+ * @type string $meta_key User meta key. Default empty.
+ * @type string $meta_value User meta value. Default empty.
+ * @type string $meta_compare Comparison operator to test the `$meta_value`. Accepts '=', '!=',
+ * '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN',
+ * 'NOT BETWEEN', 'EXISTS', 'NOT EXISTS', 'REGEXP', 'NOT REGEXP',
+ * or 'RLIKE'. Default '='.
+ * @type array $include An array of user IDs to include. Default empty array.
+ * @type array $exclude An array of user IDs to exclude. Default empty array.
+ * @type string $search Search keyword. Searches for possible string matches on columns.
+ * When `$search_columns` is left empty, it tries to determine which
+ * column to search in based on search string. Default empty.
+ * @type array $search_columns Array of column names to be searched. Accepts 'ID', 'login',
+ * 'nicename', 'email', 'url'. Default empty array.
+ * @type string $orderby Field to sort the retrieved users by. Accepts 'ID', 'display_name',
+ * 'login', 'nicename', 'email', 'url', 'registered', 'post_count', or
+ * 'meta_value'. To use 'meta_value', `$meta_key` must be also be defined.
+ * Default 'user_login'.
+ * @type string $order Designates ascending or descending order of users. Accepts 'ASC',
+ * 'DESC'. Default 'ASC'.
+ * @type int $offset Number of users to offset in retrieved results. Can be used in
+ * conjunction with pagination. Default 0.
+ * @type int $number Number of users to limit the query for. Can be used in conjunction
+ * with pagination. Value -1 (all) is not supported.
+ * Default empty (all users).
+ * @type bool $count_total Whether to count the total number of users found. If pagination is not
+ * needed, setting this to false can improve performance. Default true.
+ * @type string|array $fields Which fields to return. Single or all fields (string), or array
+ * of fields. Accepts 'ID', 'display_name', 'login', 'nicename', 'email',
+ * 'url', 'registered'. Use 'all' for all fields and 'all_with_meta' to
+ * include meta fields. Default 'all'.
+ * @type string $who Type of users to query. Accepts 'authors'. Default empty (all users).
+ * }
*/
public function prepare_query( $query = array() ) {
global $wpdb;
$this->query_from = "FROM $wpdb->users";
$this->query_where = "WHERE 1=1";
+ // Parse and sanitize 'include', for use by 'orderby' as well as 'include' below.
+ if ( ! empty( $qv['include'] ) ) {
+ $include = wp_parse_id_list( $qv['include'] );
+ } else {
+ $include = false;
+ }
+
// sorting
if ( isset( $qv['orderby'] ) ) {
if ( in_array( $qv['orderby'], array('nicename', 'email', 'url', 'registered') ) ) {
$orderby = 'ID';
} elseif ( 'meta_value' == $qv['orderby'] ) {
$orderby = "$wpdb->usermeta.meta_value";
+ } else if ( 'include' === $qv['orderby'] && ! empty( $include ) ) {
+ // Sanitized earlier.
+ $include_sql = implode( ',', $include );
+ $orderby = "FIELD( $wpdb->users.ID, $include_sql )";
} else {
$orderby = 'user_login';
}
$qv['blog_id'] = $blog_id = 0; // Prevent extra meta query
}
+ $meta_query = new WP_Meta_Query();
+ $meta_query->parse_query_vars( $qv );
+
$role = '';
if ( isset( $qv['role'] ) )
$role = trim( $qv['role'] );
$cap_meta_query['compare'] = 'like';
}
- if ( empty( $qv['meta_query'] ) || ! in_array( $cap_meta_query, $qv['meta_query'], true ) ) {
- $qv['meta_query'][] = $cap_meta_query;
+ if ( empty( $meta_query->queries ) ) {
+ $meta_query->queries = array( $cap_meta_query );
+ } elseif ( ! in_array( $cap_meta_query, $meta_query->queries, true ) ) {
+ // Append the cap query to the original queries and reparse the query.
+ $meta_query->queries = array(
+ 'relation' => 'AND',
+ array( $meta_query->queries, $cap_meta_query ),
+ );
}
- }
- $meta_query = new WP_Meta_Query();
- $meta_query->parse_query_vars( $qv );
+ $meta_query->parse_query_vars( $meta_query->queries );
+ }
if ( !empty( $meta_query->queries ) ) {
$clauses = $meta_query->get_sql( 'user', $wpdb->users, 'ID', $this );
$this->query_fields = 'DISTINCT ' . $this->query_fields;
}
- if ( ! empty( $qv['include'] ) ) {
- $ids = implode( ',', wp_parse_id_list( $qv['include'] ) );
+ if ( ! empty( $include ) ) {
+ // Sanitized earlier.
+ $ids = implode( ',', $include );
$this->query_where .= " AND $wpdb->users.ID IN ($ids)";
} elseif ( ! empty( $qv['exclude'] ) ) {
$ids = implode( ',', wp_parse_id_list( $qv['exclude'] ) );
$this->query_where .= " AND $wpdb->users.ID NOT IN ($ids)";
}
+ // Date queries are allowed for the user_registered field.
+ if ( ! empty( $qv['date_query'] ) && is_array( $qv['date_query'] ) ) {
+ $date_query = new WP_Date_Query( $qv['date_query'], 'user_registered' );
+ $this->query_where .= $date_query->get_sql();
+ }
+
/**
* Fires after the WP_User_Query has been parsed, and before
* the query is executed.
*
* @since 3.2.0
*
- * @global wpdb $wpdb WordPress database object.
+ * @global wpdb $wpdb WordPress database abstraction object.
*
* @param string $sql The SELECT FOUND_ROWS() query for the current WP_User_Query.
*/
* @since 3.1.0
* @access public
*
- * @return array Array of total users.
+ * @return int Number of total users.
*/
public function get_total() {
return $this->total_users;
*
* @since 3.1.0
*
- * @uses WP_User_Query See for default arguments and information.
+ * @see WP_User_Query
*
- * @param array $args Optional. Array of arguments.
+ * @param array $args Optional. Arguments to retrieve users. See {@see WP_User_Query::prepare_query()}
+ * for more information on accepted arguments.
* @return array List of users.
*/
function get_users( $args = array() ) {
* Find out whether a user is a member of a given blog.
*
* @since MU 1.1
- * @uses get_blogs_of_user()
*
* @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.
* Post meta data is called "Custom Fields" on the Administration Screens.
*
* @since 3.0.0
- * @uses add_metadata()
* @link http://codex.wordpress.org/Function_Reference/add_user_meta
*
* @param int $user_id User ID.
* allows removing all metadata matching key, if needed.
*
* @since 3.0.0
- * @uses delete_metadata()
* @link http://codex.wordpress.org/Function_Reference/delete_user_meta
*
* @param int $user_id user ID
* Retrieve user meta field for a user.
*
* @since 3.0.0
- * @uses get_metadata()
* @link http://codex.wordpress.org/Function_Reference/get_user_meta
*
* @param int $user_id User ID.
* If the meta field for the user does not exist, it will be added.
*
* @since 3.0.0
- * @uses update_metadata
* @link http://codex.wordpress.org/Function_Reference/update_user_meta
*
* @param int $user_id User ID.
/**
* Filter a user field value in the 'edit' context.
*
- * The dynamic portion of the hook name, $field, refers to the prefixed user
+ * The dynamic portion of the hook name, `$field`, refers to the prefixed user
* field being filtered, such as 'user_login', 'user_email', 'first_name', etc.
*
* @since 2.9.0
/**
* Filter the value of a user field in the 'db' context.
*
- * The dynamic portion of the hook name, $field, refers to the prefixed user
+ * The dynamic portion of the hook name, `$field`, refers to the prefixed user
* field being filtered, such as 'user_login', 'user_email', 'first_name', etc.
*
* @since 2.9.0
/**
* Filter the value of a user field in a standard context.
*
- * The dynamic portion of the hook name, $field, refers to the prefixed user
+ * The dynamic portion of the hook name, `$field`, refers to the prefixed user
* field being filtered, such as 'user_login', 'user_email', 'first_name', etc.
*
* @since 2.9.0
* Checks whether an username is valid.
*
* @since 2.0.1
- * @uses apply_filters() Calls 'validate_username' hook on $valid check and $username as parameters
*
* @param string $username Username.
* @return bool Whether username given is valid
if ( ! $update && username_exists( $user_login ) ) {
return new WP_Error( 'existing_user_login', __( 'Sorry, that username already exists!' ) );
}
- if ( empty( $userdata['user_nicename'] ) ) {
- $user_nicename = sanitize_title( $user_login );
+
+ // If a nicename is provided, remove unsafe user characters before
+ // using it. Otherwise build a nicename from the user_login.
+ if ( ! empty( $userdata['user_nicename'] ) ) {
+ $user_nicename = sanitize_user( $userdata['user_nicename'], true );
} else {
- $user_nicename = $userdata['user_nicename'];
+ $user_nicename = $user_login;
}
+ $user_nicename = sanitize_title( $user_nicename );
+
// Store values to save in user meta.
$meta = array();
$data = wp_unslash( $compacted );
if ( $update ) {
+ if ( $user_email !== $old_user_data->user_email ) {
+ $data['user_activation_key'] = '';
+ }
$wpdb->update( $wpdb->users, $data, compact( 'ID' ) );
$user_id = (int) $ID;
} else {
* A simpler way of inserting an user into the database.
*
* Creates a new user with just the username, password, and email. For more
- * complex user creation use wp_insert_user() to specify more information.
+ * complex user creation use {@see wp_insert_user()} to specify more information.
*
* @since 2.0.0
* @see wp_insert_user() More complete way to create a new user
*
* @param string $username The user's username.
* @param string $password The user's password.
- * @param string $email The user's email (optional).
+ * @param string $email Optional. The user's email. Default empty.
* @return int The new user's ID.
*/
function wp_create_user($username, $password, $email = '') {
* @since 3.3.0
* @access private
*
- * @param object $user WP_User instance.
+ * @param WP_User $user WP_User instance.
* @return array
*/
function _get_additional_user_keys( $user ) {
return wp_get_user_contact_methods( $user );
}
+/**
+ * Gets the text suggesting how to create strong passwords.
+ *
+ * @since 4.1.0
+ *
+ * @return string The password hint text.
+ */
+function wp_get_password_hint() {
+ $hint = __( 'Hint: The password should be at least seven characters long. To make it stronger, use upper and lower case letters, numbers, and symbols like ! " ? $ % ^ & ).' );
+
+ /**
+ * Filter the text describing the site's password complexity policy.
+ *
+ * @since 4.1.0
+ *
+ * @param string $hint The password hint text.
+ */
+ return apply_filters( 'password_hint', $hint );
+}
+
/**
* Retrieves a user row based on password reset key and login
*
scripts.mit.edu / autoinstalls / wordpress.git / blobdiff