* WordPress User API
*
* @package WordPress
+ * @subpackage Users
*/
/**
*
* @param array $credentials Optional. User info in order to sign on.
* @param bool $secure_cookie Optional. Whether to use secure cookie.
- * @return object Either WP_Error on failure, or WP_User on success.
+ * @return WP_User|WP_Error WP_User on success, WP_Error on failure.
*/
-function wp_signon( $credentials = '', $secure_cookie = '' ) {
+function wp_signon( $credentials = array(), $secure_cookie = '' ) {
if ( empty($credentials) ) {
if ( ! empty($_POST['log']) )
$credentials['user_login'] = $_POST['log'];
else
$credentials['remember'] = false;
- // TODO do we deprecate the wp_authentication action?
- do_action_ref_array('wp_authenticate', array(&$credentials['user_login'], &$credentials['user_password']));
+ /**
+ * 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();
- $secure_cookie = apply_filters('secure_signon_cookie', $secure_cookie, $credentials);
+ /**
+ * Filter 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;
}
wp_set_auth_cookie($user->ID, $credentials['remember'], $secure_cookie);
- do_action('wp_login', $user->user_login, $user);
+ /**
+ * 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;
}
/**
* Authenticate the user using the username and password.
+ *
+ * @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.
*/
-add_filter('authenticate', 'wp_authenticate_username_password', 20, 3);
function wp_authenticate_username_password($user, $username, $password) {
- if ( is_a($user, 'WP_User') ) { return $user; }
+ if ( is_a( $user, 'WP_User' ) ) {
+ return $user;
+ }
if ( empty($username) || empty($password) ) {
if ( is_wp_error( $user ) )
if ( !$user )
return new WP_Error( 'invalid_username', sprintf( __( '<strong>ERROR</strong>: Invalid username. <a href="%s" title="Password Lost and Found">Lost your password</a>?' ), wp_lostpassword_url() ) );
- $user = apply_filters('wp_authenticate_user', $user, $password);
+ /**
+ * Filter 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;
/**
* Authenticate the user using the WordPress auth cookie.
+ *
+ * @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. 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 ( is_a($user, 'WP_User') ) { return $user; }
+ if ( is_a( $user, 'WP_User' ) ) {
+ return $user;
+ }
if ( empty($username) && empty($password) ) {
$user_id = wp_validate_auth_cookie();
}
/**
- * For multisite blogs, check if the authenticated user has been marked as a
+ * For Multisite blogs, check 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 && is_a( $user, 'WP_User' ) && is_multisite() ) {
+ /**
+ * Filter 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 );
if ( $spammed )
return $user;
}
+/**
+ * Validate 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 determine_current_user filter, rather than API.
+ *
+ * @since 3.9.0
+ *
+ * @param int|bool $user 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.
+ */
+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' );
+}
+
/**
* Number of posts user has written.
*
* @since 3.0.0
- * @uses $wpdb WordPress database object for queries.
+ *
+ * @global wpdb $wpdb WordPress database object for queries.
*
* @param int $userid User ID.
* @return int Amount of posts user has written.
$count = $wpdb->get_var( "SELECT COUNT(*) FROM $wpdb->posts $where" );
- return apply_filters('get_usernumposts', $count, $userid);
+ /**
+ * Filter the number of posts a user has written.
+ *
+ * @since 2.7.0
+ *
+ * @param int $count The user's post count.
+ * @param int $userid User ID.
+ */
+ return apply_filters( 'get_usernumposts', $count, $userid );
}
/**
* The option will first check for the per site name and then the per Network name.
*
* @since 2.0.0
- * @uses $wpdb WordPress database object for queries.
- * @uses apply_filters() Calls 'get_user_option_$option' hook with result,
- * option parameter, and user data object.
- *
- * @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.
- * @return mixed
+ *
+ * @global wpdb $wpdb WordPress database object for queries.
+ *
+ * @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.
+ * @return mixed User option value on success, false on failure.
*/
function get_user_option( $option, $user = 0, $deprecated = '' ) {
global $wpdb;
else
$result = false;
- return apply_filters("get_user_option_{$option}", $result, $option, $user);
+ /**
+ * Filter 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 );
}
/**
* Deletes the user option if $newvalue is empty.
*
* @since 2.0.0
- * @uses $wpdb WordPress database object for queries
*
- * @param int $user_id User ID
+ * @global wpdb $wpdb WordPress database object for queries.
+ *
+ * @param int $user_id User ID.
* @param string $option_name User option name.
- * @param mixed $newvalue User option value.
- * @param bool $global Optional. Whether option name is global or blog specific. Default false (blog specific).
- * @return unknown
+ * @param mixed $newvalue User option value.
+ * @param bool $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, $global = false ) {
global $wpdb;
* it will prepend the WordPress table prefix to the option name.
*
* @since 3.0.0
- * @uses $wpdb WordPress database object for queries
*
- * @param int $user_id User ID
+ * @global wpdb $wpdb WordPress database object for queries.
+ *
+ * @param int $user_id User ID
* @param string $option_name User option name.
- * @param bool $global Optional. Whether option name is global or blog specific. Default false (blog specific).
- * @return unknown
+ * @param bool $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, $global = false ) {
global $wpdb;
var $query_limit;
/**
- * PHP5 constructor
+ * PHP5 constructor.
*
* @since 3.1.0
*
- * @param string|array $args The query variables
+ * @param string|array $args Optional. The query variables.
* @return WP_User_Query
*/
function __construct( $query = null ) {
- if ( !empty( $query ) ) {
+ if ( ! empty( $query ) ) {
+ $this->prepare_query( $query );
+ $this->query();
+ }
+ }
+
+ /**
+ * Prepare the query variables.
+ *
+ * @since 3.1.0
+ *
+ * @param string|array $args Optional. The query variables.
+ */
+ function prepare_query( $query = array() ) {
+ global $wpdb;
+
+ if ( empty( $this->query_vars ) || ! empty( $query ) ) {
+ $this->query_limit = null;
$this->query_vars = wp_parse_args( $query, array(
'blog_id' => $GLOBALS['blog_id'],
'role' => '',
'fields' => 'all',
'who' => ''
) );
-
- $this->prepare_query();
- $this->query();
}
- }
-
- /**
- * Prepare the query variables
- *
- * @since 3.1.0
- * @access private
- */
- function prepare_query() {
- global $wpdb;
$qv =& $this->query_vars;
$search_columns = array('user_login', 'user_nicename');
}
+ /**
+ * Filter the columns to search in a WP_User_Query search.
+ *
+ * The default columns depend on the search term, and include 'user_email',
+ * 'user_login', 'ID', 'user_url', and 'user_nicename'.
+ *
+ * @since 3.6.0
+ *
+ * @param array $search_columns Array of column names to be searched.
+ * @param string $search Text being searched.
+ * @param WP_User_Query $this The current WP_User_Query instance.
+ */
$search_columns = apply_filters( 'user_search_columns', $search_columns, $search, $this );
$this->query_where .= $this->get_search_sql( $search, $search_columns, $wild );
$cap_meta_query['compare'] = 'like';
}
- $qv['meta_query'][] = $cap_meta_query;
+ if ( empty( $qv['meta_query'] ) || ! in_array( $cap_meta_query, $qv['meta_query'], true ) ) {
+ $qv['meta_query'][] = $cap_meta_query;
+ }
}
$meta_query = new WP_Meta_Query();
$this->query_where .= " AND $wpdb->users.ID NOT IN ($ids)";
}
+ /**
+ * Fires after the WP_User_Query has been parsed, and before
+ * the query is executed.
+ *
+ * The passed WP_User_Query object contains SQL parts formed
+ * from parsing the given query.
+ *
+ * @since 3.1.0
+ *
+ * @param WP_User_Query $this The current WP_User_Query instance,
+ * passed by reference.
+ */
do_action_ref_array( 'pre_user_query', array( &$this ) );
}
/**
- * Execute the query, with the current variables
+ * Execute the query, with the current variables.
*
* @since 3.1.0
- * @access private
+ *
+ * @global wpdb $wpdb WordPress database object for queries.
*/
function query() {
global $wpdb;
$qv =& $this->query_vars;
+ $query = "SELECT $this->query_fields $this->query_from $this->query_where $this->query_orderby $this->query_limit";
+
if ( is_array( $qv['fields'] ) || 'all' == $qv['fields'] ) {
- $this->results = $wpdb->get_results("SELECT $this->query_fields $this->query_from $this->query_where $this->query_orderby $this->query_limit");
+ $this->results = $wpdb->get_results( $query );
} else {
- $this->results = $wpdb->get_col("SELECT $this->query_fields $this->query_from $this->query_where $this->query_orderby $this->query_limit");
+ $this->results = $wpdb->get_col( $query );
}
+ /**
+ * Filter SELECT FOUND_ROWS() query for the current WP_User_Query instance.
+ *
+ * @since 3.2.0
+ *
+ * @global wpdb $wpdb WordPress database object.
+ *
+ * @param string $sql The SELECT FOUND_ROWS() query for the current WP_User_Query.
+ */
if ( isset( $qv['count_total'] ) && $qv['count_total'] )
$this->total_users = $wpdb->get_var( apply_filters( 'found_users_query', 'SELECT FOUND_ROWS()' ) );
}
/**
- * Return the list of users
+ * Return the list of users.
*
* @since 3.1.0
* @access public
*
- * @return array
+ * @return array Array of results.
*/
function get_results() {
return $this->results;
}
/**
- * Return the total number of users for the current query
+ * Return the total number of users for the current query.
*
* @since 3.1.0
* @access public
*
- * @return array
+ * @return array Array of total users.
*/
function get_total() {
return $this->total_users;
* Retrieve list of users matching criteria.
*
* @since 3.1.0
- * @uses $wpdb
+ *
* @uses WP_User_Query See for default arguments and information.
*
- * @param array $args Optional.
+ * @param array $args Optional. Array of arguments.
* @return array List of users.
*/
function get_users( $args = array() ) {
*
* @since 3.0.0
*
- * @param int $user_id User ID
- * @param bool $all Whether to retrieve all blogs, or only blogs that are not marked as deleted, archived, or spam.
- * @return array A list of the user's blogs. An empty array if the user doesn't exist or belongs to no blogs.
+ * @global wpdb $wpdb WordPress database object for queries.
+ *
+ * @param int $user_id User ID
+ * @param bool $all Whether to retrieve all blogs, or only blogs that are not
+ * marked as deleted, archived, or spam.
+ * @return array A list of the user's blogs. An empty array if the user doesn't exist
+ * or belongs to no blogs.
*/
function get_blogs_of_user( $user_id, $all = false ) {
global $wpdb;
}
}
+ /**
+ * Filter the list of blogs a user belongs to.
+ *
+ * @since MU
+ *
+ * @param array $blogs An array of blog objects belonging to the user.
+ * @param int $user_id User ID.
+ * @param bool $all Whether the returned blogs array should contain all blogs, including
+ * those marked 'deleted', 'archived', or 'spam'. Default false.
+ */
return apply_filters( 'get_blogs_of_user', $blogs, $user_id, $all );
}
* @param string $meta_key Metadata key.
* @param mixed $meta_value Metadata value.
* @param mixed $prev_value Optional. Previous value to check before removing.
- * @return bool True on success, false on failure.
+ * @return int|bool Meta ID if the key didn't exist, true on successful update, false on failure.
*/
function update_user_meta($user_id, $meta_key, $meta_value, $prev_value = '') {
return update_metadata('user', $user_id, $meta_key, $meta_value, $prev_value);
* </ol>
*
* @since 2.3.0
- * @uses $wpdb WordPress database object for queries
*
- * @param string|array $args Optional. Override defaults.
+ * @global wpdb $wpdb WordPress database object for queries.
+ *
+ * @todo Hash-notate arguments array.
+ *
+ * @param string|array $args Optional. Array of user arguments.
* @return string|null Null on display. String of HTML content on retrieve.
*/
function wp_dropdown_users( $args = '' ) {
$output .= "</select>";
}
- $output = apply_filters('wp_dropdown_users', $output);
+ /**
+ * Filter the wp_dropdown_users() HTML output.
+ *
+ * @since 2.3.0
+ *
+ * @param string $output HTML output generated by wp_dropdown_users().
+ */
+ $output = apply_filters( 'wp_dropdown_users', $output );
if ( $echo )
echo $output;
* when calling filters.
*
* @since 2.3.0
- * @uses apply_filters() Calls 'edit_$field' passing $value and $user_id if $context == 'edit'.
- * $field is prefixed with 'user_' if it isn't already.
- * @uses apply_filters() Calls 'pre_$field' passing $value if $context == 'db'. $field is prefixed with
- * 'user_' if it isn't already.
- * @uses apply_filters() Calls '$field' passing $value, $user_id and $context if $context == anything
- * other than 'raw', 'edit' and 'db'. $field is prefixed with 'user_' if it isn't already.
*
* @param string $field The user Object field name.
* @param mixed $value The user Object value.
if ( 'edit' == $context ) {
if ( $prefixed ) {
- $value = apply_filters("edit_{$field}", $value, $user_id);
+
+ /** This filter is documented in wp-includes/post.php */
+ $value = apply_filters( "edit_{$field}", $value, $user_id );
} else {
- $value = apply_filters("edit_user_{$field}", $value, $user_id);
+
+ /**
+ * Filter a user field value in the 'edit' context.
+ *
+ * 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
+ *
+ * @param mixed $value Value of the prefixed user field.
+ * @param int $user_id User ID.
+ */
+ $value = apply_filters( "edit_user_{$field}", $value, $user_id );
}
if ( 'description' == $field )
$value = esc_attr($value);
} else if ( 'db' == $context ) {
if ( $prefixed ) {
- $value = apply_filters("pre_{$field}", $value);
+ /** This filter is documented in wp-includes/post.php */
+ $value = apply_filters( "pre_{$field}", $value );
} else {
- $value = apply_filters("pre_user_{$field}", $value);
+
+ /**
+ * Filter the value of a user field in the 'db' context.
+ *
+ * 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
+ *
+ * @param mixed $value Value of the prefixed user field.
+ */
+ $value = apply_filters( "pre_user_{$field}", $value );
}
} else {
// Use display filters by default.
- if ( $prefixed )
- $value = apply_filters($field, $value, $user_id, $context);
- else
- $value = apply_filters("user_{$field}", $value, $user_id, $context);
+ if ( $prefixed ) {
+
+ /** This filter is documented in wp-includes/post.php */
+ $value = apply_filters( $field, $value, $user_id, $context );
+ } else {
+
+ /**
+ * Filter the value of a user field in a standard context.
+ *
+ * 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
+ *
+ * @param mixed $value The user object value to sanitize.
+ * @param int $user_id User ID.
+ * @param string $context The context to filter within.
+ */
+ $value = apply_filters( "user_{$field}", $value, $user_id, $context );
+ }
}
if ( 'user_url' == $field )
* Checks whether the given email exists.
*
* @since 2.1.0
- * @uses $wpdb
*
* @param string $email Email.
* @return bool|int The user's ID on success, and false on failure.
function validate_username( $username ) {
$sanitized = sanitize_user( $username, true );
$valid = ( $sanitized == $username );
+ /**
+ * Filter whether the provided username is valid or not.
+ *
+ * @since 2.0.1
+ *
+ * @param bool $valid Whether given username is valid.
+ * @param string $username Username to check.
+ */
return apply_filters( 'validate_username', $valid, $username );
}
* 'yim' - User's Yahoo IM account.
*
* @since 2.0.0
- * @uses $wpdb WordPress database layer.
- * @uses apply_filters() Calls filters for most of the $userdata fields with the prefix 'pre_user'. See note above.
- * @uses do_action() Calls 'profile_update' hook when updating giving the user's ID
- * @uses do_action() Calls 'user_register' hook when creating a new user giving the user's ID
+ *
+ * @global wpdb $wpdb WordPress database object for queries.
+ *
+ * @todo Hash-notate arguments array.
*
* @param mixed $userdata An array of user data or a user object of type stdClass or WP_User.
* @return int|WP_Error The newly created user's ID or a WP_Error object if the user could not be created.
}
$user_login = sanitize_user($user_login, true);
- $user_login = apply_filters('pre_user_login', $user_login);
+
+ /**
+ * Filter a username after it has been sanitized.
+ *
+ * This filter is called before the user is created or updated.
+ *
+ * @since 2.0.3
+ *
+ * @param string $user_login Username after it has been sanitized.
+ */
+ $user_login = apply_filters( 'pre_user_login', $user_login );
//Remove any non-printable chars from the login string to see if we have ended up with an empty username
$user_login = trim($user_login);
if ( empty($user_nicename) )
$user_nicename = sanitize_title( $user_login );
- $user_nicename = apply_filters('pre_user_nicename', $user_nicename);
+
+ /**
+ * Filter a user's nicename before the user is created or updated.
+ *
+ * @since 2.0.3
+ *
+ * @param string $user_nicename The user's nicename.
+ */
+ $user_nicename = apply_filters( 'pre_user_nicename', $user_nicename );
if ( empty($user_url) )
$user_url = '';
- $user_url = apply_filters('pre_user_url', $user_url);
+
+ /**
+ * Filter a user's URL before the user is created or updated.
+ *
+ * @since 2.0.3
+ *
+ * @param string $user_url The user's URL.
+ */
+ $user_url = apply_filters( 'pre_user_url', $user_url );
if ( empty($user_email) )
$user_email = '';
- $user_email = apply_filters('pre_user_email', $user_email);
+
+ /**
+ * Filter a user's email before the user is created or updated.
+ *
+ * @since 2.0.3
+ *
+ * @param string $user_email The user's email.
+ */
+ $user_email = apply_filters( 'pre_user_email', $user_email );
if ( !$update && ! defined( 'WP_IMPORTING' ) && email_exists($user_email) )
return new WP_Error( 'existing_user_email', __( 'Sorry, that email address is already used!' ) );
if ( empty($nickname) )
$nickname = $user_login;
- $nickname = apply_filters('pre_user_nickname', $nickname);
+
+ /**
+ * Filter a user's nickname before the user is created or updated.
+ *
+ * @since 2.0.3
+ *
+ * @param string $nickname The user's nickname.
+ */
+ $nickname = apply_filters( 'pre_user_nickname', $nickname );
if ( empty($first_name) )
$first_name = '';
- $first_name = apply_filters('pre_user_first_name', $first_name);
+
+ /**
+ * Filter a user's first name before the user is created or updated.
+ *
+ * @since 2.0.3
+ *
+ * @param string $first_name The user's first name.
+ */
+ $first_name = apply_filters( 'pre_user_first_name', $first_name );
if ( empty($last_name) )
$last_name = '';
- $last_name = apply_filters('pre_user_last_name', $last_name);
+
+ /**
+ * Filter a user's last name before the user is created or updated.
+ *
+ * @since 2.0.3
+ *
+ * @param string $last_name The user's last name.
+ */
+ $last_name = apply_filters( 'pre_user_last_name', $last_name );
if ( empty( $display_name ) ) {
if ( $update )
else
$display_name = $user_login;
}
+
+ /**
+ * Filter a user's display name before the user is created or updated.
+ *
+ * @since 2.0.3
+ *
+ * @param string $display_name The user's display name.
+ */
$display_name = apply_filters( 'pre_user_display_name', $display_name );
if ( empty($description) )
$description = '';
- $description = apply_filters('pre_user_description', $description);
+
+ /**
+ * Filter a user's description before the user is created or updated.
+ *
+ * @since 2.0.3
+ *
+ * @param string $description The user's description.
+ */
+ $description = apply_filters( 'pre_user_description', $description );
if ( empty($rich_editing) )
$rich_editing = 'true';
wp_cache_delete($user_id, 'users');
wp_cache_delete($user_login, 'userlogins');
- if ( $update )
- do_action('profile_update', $user_id, $old_user_data);
- else
- do_action('user_register', $user_id);
+ if ( $update ) {
+ /**
+ * Fires immediately after an existing user is updated.
+ *
+ * @since 2.0.0
+ *
+ * @param int $user_id User ID.
+ * @param object $old_user_data Object containing user's data prior to update.
+ */
+ do_action( 'profile_update', $user_id, $old_user_data );
+ } else {
+ /**
+ * Fires immediately after a new user is registered.
+ *
+ * @since 1.5.0
+ *
+ * @param int $user_id User ID.
+ */
+ do_action( 'user_register', $user_id );
+ }
return $user_id;
}
* cleared.
*
* @since 2.0.0
- * @see wp_insert_user() For what fields can be set in $userdata
+ *
+ * @see wp_insert_user() For what fields can be set in $userdata.
*
* @param mixed $userdata An array of user data or a user object of type stdClass or WP_User.
* @return int|WP_Error The updated user's ID or a WP_Error object if the user could not be updated.
* hashing process. This field is now hashed; old values are no longer accepted
* but have a different WP_Error code so good user feedback can be provided.
*
- * @uses $wpdb WordPress Database object
+ * @global wpdb $wpdb WordPress database object for queries.
*
* @param string $key Hash to validate sending user's password.
* @param string $login The user login.
* @param string $new_pass New password for the user in plaintext
*/
function reset_password( $user, $new_pass ) {
+ /**
+ * Fires before the user's password is reset.
+ *
+ * @since 1.5.0
+ *
+ * @param object $user The user.
+ * @param string $new_pass New user password.
+ */
do_action( 'password_reset', $user, $new_pass );
wp_set_password( $new_pass, $user->ID );
$errors = new WP_Error();
$sanitized_user_login = sanitize_user( $user_login );
+ /**
+ * Filter the email address of a user being registered.
+ *
+ * @since 2.1.0
+ *
+ * @param string $user_email The email address of the new user.
+ */
$user_email = apply_filters( 'user_registration_email', $user_email );
// Check the username
$errors->add( 'email_exists', __( '<strong>ERROR</strong>: This email is already registered, please choose another one.' ) );
}
+ /**
+ * Fires when submitting registration form data, before the user is created.
+ *
+ * @since 2.1.0
+ *
+ * @param string $sanitized_user_login The submitted username after being sanitized.
+ * @param string $user_email The submitted email.
+ * @param WP_Error $errors Contains any errors with submitted username and email,
+ * e.g., an empty field, an invalid username or email,
+ * or an existing username or email.
+ */
do_action( 'register_post', $sanitized_user_login, $user_email, $errors );
+ /**
+ * Filter the errors encountered when a new user is being registered.
+ *
+ * The filtered WP_Error object may, for example, contain errors for an invalid
+ * or existing username or email address. A WP_Error object should always returned,
+ * but may or may not contain errors.
+ *
+ * If any errors are present in $errors, this will abort the user's registration.
+ *
+ * @since 2.1.0
+ *
+ * @param WP_Error $errors A WP_Error object containing any errors encountered
+ * during registration.
+ * @param string $sanitized_user_login User's username after it has been sanitized.
+ * @param string $user_email User's email.
+ */
$errors = apply_filters( 'registration_errors', $errors, $sanitized_user_login, $user_email );
if ( $errors->get_error_code() )
scripts.mit.edu / autoinstalls / wordpress.git / blobdiff