X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/874d2a2f468a0d1e69aab49b1fe2d9d79d3e1142..caeaf8dc94b5e3f75dc98ec92dc7b76049cdddb6:/wp-includes/user.php diff --git a/wp-includes/user.php b/wp-includes/user.php index 4244642c..3640980f 100644 --- a/wp-includes/user.php +++ b/wp-includes/user.php @@ -19,8 +19,8 @@ * * @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 = '' ) { @@ -229,7 +229,7 @@ function wp_authenticate_spam_check( $user ) { * * @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. @@ -250,16 +250,18 @@ function wp_validate_logged_in_cookie( $user_id ) { * 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" ); @@ -267,11 +269,13 @@ function count_user_posts($userid) { * 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 ); } /** @@ -316,8 +320,6 @@ function count_many_users_posts( $users, $post_type = 'post', $public_only = fal * * @since MU * - * @uses wp_get_current_user - * * @return int The current user's ID */ function get_current_user_id() { @@ -343,7 +345,7 @@ 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 = '' ) { @@ -369,7 +371,7 @@ 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 * @@ -439,6 +441,8 @@ function delete_user_option( $user_id, $option_name, $global = false ) { * WordPress User Query class. * * @since 3.1.0 + * + * @see WP_User_Query::prepare_query() for information on accepted arguments. */ class WP_User_Query { @@ -481,7 +485,7 @@ 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 ) { @@ -495,8 +499,45 @@ class WP_User_Query { * 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; @@ -559,6 +600,13 @@ class WP_User_Query { $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') ) ) { @@ -582,6 +630,10 @@ class WP_User_Query { $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'; } @@ -665,6 +717,9 @@ class WP_User_Query { $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'] ); @@ -678,13 +733,18 @@ class WP_User_Query { $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 ); @@ -695,14 +755,21 @@ class WP_User_Query { $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. @@ -743,7 +810,7 @@ class WP_User_Query { * * @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. */ @@ -846,7 +913,7 @@ class 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; @@ -924,9 +991,10 @@ class WP_User_Query { * * @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() ) { @@ -1045,7 +1113,6 @@ function get_blogs_of_user( $user_id, $all = false ) { * 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. @@ -1071,7 +1138,6 @@ function is_user_member_of_blog( $user_id = 0, $blog_id = 0 ) { * 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. @@ -1092,7 +1158,6 @@ function add_user_meta($user_id, $meta_key, $meta_value, $unique = false) { * 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 @@ -1108,7 +1173,6 @@ function delete_user_meta($user_id, $meta_key, $meta_value = '') { * 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. @@ -1130,7 +1194,6 @@ function get_user_meta($user_id, $key = '', $single = false) { * 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. @@ -1436,7 +1499,7 @@ function sanitize_user_field($field, $value, $user_id, $context) { /** * 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 @@ -1460,7 +1523,7 @@ function sanitize_user_field($field, $value, $user_id, $context) { /** * 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 @@ -1480,7 +1543,7 @@ function sanitize_user_field($field, $value, $user_id, $context) { /** * 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 @@ -1573,7 +1636,6 @@ function email_exists( $email ) { * 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 @@ -1676,12 +1738,17 @@ function wp_insert_user( $userdata ) { 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(); @@ -1948,14 +2015,14 @@ function wp_update_user($userdata) { * 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 = '') { @@ -1973,7 +2040,7 @@ 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 ) { @@ -2022,6 +2089,26 @@ function _wp_get_user_contactmethods( $user = null ) { 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 *