Creating and Managing Users

Inserting  Users Inserting  Users

To add a user use ether wp_insert_user or wp_create_user.   wp_create_user ONLY creates a user, and does not allow for managing any extra user fields. wp_insert_user allows for filling in all user fields.

<?php wp_insert_user( $userdata ); ?>

Parameters Parameters

$userdata
(mixed) (required) An array of user data, stdClass or WP_User object.
Default: None

Top ↑

Return Values Return Values

(mixed) If successful, returns the newly-created user’s user_id, otherwise returns a WP_Error object.

Top ↑

Examples Examples

Below is an example showing how to insert a new user with the website profile field filled.

<?php

$website = "http://example.com";
$userdata = array(
    'user_login'  =>  'login_name',
    'user_url'    =>  $website,
    'user_pass'   =>  NULL  // When creating an user, `user_pass` is expected.
);

$user_id = wp_insert_user( $userdata ) ;

//On success
if( !is_wp_error($user_id) ) {
 echo "User created : ". $user_id;
} ?>

 

If successful, returns the newly-created user’s user_id, otherwise returns a WP_Error object.

The $userdata array can contain the following fields
Field Name Description Associated Filter
ID An integer that will be used for updating an existing user. (none)
user_pass A string that contains the plain text password for the user. pre_user_pass
user_login A string that contains the user’s username for logging in. pre_user_login
user_nicename A string that contains a URL-friendly name for the user. The default is the user’s username. pre_user_nicename
user_url A string containing the user’s URL for the user’s web site. pre_user_url
user_email A string containing the user’s email address. pre_user_email
display_name A string that will be shown on the site. Defaults to user’s username. It is likely that you will want to change this, for both appearance and security through obscurity (that is if you dont use and delete the default admin user). pre_user_display_name
nickname The user’s nickname, defaults to the user’s username. pre_user_nickname
first_name The user’s first name. pre_user_first_name
last_name The user’s last name. pre_user_last_name
description A string containing content about the user. pre_user_description
rich_editing A string for whether to enable the rich editor or not. False if not empty. (none)
user_registered The date the user registered. Format is Y-m-d H:i:s. (none)
role A string used to set the user’s role. (none)
jabber User’s Jabber account. (none)
aim User’s AOL IM account. (none)
yim User’s Yahoo IM account. (none)

Top ↑

Notes Notes

Uses: $wpdb WordPress database layer.
Uses: apply_filters() Calls filters for most of the $userdata fields with the prefix ‘pre_user’. See description 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
If there is no ID, a new user will be created. If you pass an ID , the user with that ID will be updated, and these meta fields are updated if set in $userdata otherwise they are set to null:

 first_name,
 last_name,
 nickname,
 description,
 rich_editing,
 comment_shortcuts,
 admin_color,
 use_ssl,
 show_admin_bar_front

When performing an update operation using wp_insert_user, user_pass should be the hashed password and not the plain text password.

 

Top ↑

Creating Users Creating Users

<?php wp_create_user( $username, $password, $email ); ?>

Top ↑

Description Description

The wp_create_user function allows you to insert a new user into the WordPress database. It uses the $wpdb class to escape the variable values, preparing it for insertion into the database. Then the PHP compact() function is used to create an array with these values. To create a user with additional parameters, use wp_insert_user().

Top ↑

Example Example

As used in wp-admin/upgrade-functions.php:

$user_id = username_exists( $user_name );
    if ( !$user_id and email_exists($user_email) == false ) {
        $random_password = wp_generate_password( $length=12, $include_standard_special_chars=false );
    $user_id = wp_create_user( $user_name, $random_password, $user_email );
    } else {
    $random_password = __('User already exists. Password inherited.');
}

Parameters Parameters

$username
(string) (required) The username of the user to be created.
Default: None
$password
(string) (required) The password of the user to be created.
Default: None
$email
(string) (optional) The email address of the user to be created.
Default: None

Top ↑

Returns Returns

When successful – this function returns the user ID of the created user. In case of failure (username or email already exists) the function returns an error object, with these possible values and messages;
empty_user_login, Cannot create a user with an empty login name.
existing_user_login, This username is already registered.
existing_user_email, This email address is already registered.

Top ↑

Updating  Users Updating  Users

<?php wp_update_user( $userdata ) ?>

Description
This function updates a single user in the database. This update can contain multiple pieces of user metadata as an array.
To update a single piece of user metadata, use update_user_meta() instead.
To create a new user, use wp_insert_user() instead.

Note: If current user’s password is being updated, then the cookies will be cleared!

Parameters Parameters

$userdata
(mixed) (required) An array of user data, stdClass or WP_User object.
Default: None
Return Values (mixed)
If successful, returns the user_id, otherwise returns a WP_Error object.

Top ↑

Examples Examples

Below is an example showing how to update a user’s website profile field:

<?php

$user_id = 1;
$website = 'http://wordpress.org';

$user_id = wp_update_user( array( 'ID' => $user_id, 'user_url' => $website ) );

if ( is_wp_error( $user_id ) ) {
	// There was an error, probably that user doesn't exist.
} else {
	// Success!
}

 

Top ↑

Delete Users Delete Users

<?php wp_delete_user( $id, $reassign ); ?></code>

Top ↑

Description Description

Remove user and optionally reassign posts and links to another user.
If the $reassign parameter is not assigned to a User ID, then all posts will be deleted of that user. The action ‘delete_user’ that is passed the User ID being deleted will be run after the posts are either reassigned or deleted. The user meta will also be deleted that are for that User ID.

Parameters Parameters

$id
(integer) (required) User ID.
Default: None
$reassign
(integer) (optional) Reassign posts and links to new User ID.
Default: null
Return Values
(boolean)
True when finished.

Top ↑

Examples Examples

Allow users to terminate their user accounts.

wp_delete_user( $user_id );

Top ↑

Notes Notes

If you wish to use this function in a plugin then you must include the ./wp-admin/includes/user.php file in your plugin function, else it will throw a ‘call to undefined function’ error
Uses global: (object) $wpdb
This is an Admin function.