Programmatically Create a User in WordPress

If you're an advanced developer or just want the TL;DR version of this, skip to the code.

When it comes to building a certain type of web app, I obviously think that WordPress is a viable option. Out of all of the contract work I’ve done in the past couple of years, about half of the projects have required some form of user management.

That is, they usually want users to create their own accounts, set a few fields such as their name and email address, and then be emailed when all is setup.

Out of the box, WordPress offers easy user management through its dashboard and if you’re running some type of blog or editorial site, there’s no need to deviate. But if you’re building an application, there are alternative ways to handle users.

Case in point: say that designer has created a solid look and feel for the site. If you force users to use the built-in dashboard to create or manage their profiles, then you’re yanking them out of the site, dropping them into some new experience, and then returning them to the site from which they came.

Lame, right?

There are better ways to introduce user registration and profile management into an app built on WordPress. Though your mileage may vary based on the needs of you project, here’s a how you can programmatically create a user in WordPress.

Before looking at any code, I’m making a number of assumptions throughout the code below. Some may setup registration using Ajax and GET requests; others may use POST requests and do some other type of processing in addition to creating the users.

Whatever the case, all options converge to this:

  • Create a user
  • Set the role
  • Send an email

However you opt to go about getting this data is up to you. To that point, I’ve tried to mark where I’m making assumptions and where the general principles of the API apply.

Required User Data

At the basic level, you really only need two pieces of information to create a user:

  1. An email address
  2. A password

Sure, you can give the user the ability to specify a username if they’d like, but unless the requirements state that a username should be created, I default to an email address every single time. After all, they are unique to each person (and whether we like it or not, they’re kind of our common denominator when it comes to our ID’s on the Internet).

For passwords, you can give users the option to create their own or you can actually let WordPress generate one and then let users change it later. Allowing WordPress to generate it ensures that a secure password will be created and lowers the barrier of registration – doing it this way, they really only have to specify one thing: an email address.

Anyway, so those are two assumptions I’m making:

  1. WordPress will be generating the password
  2. A user’s email address will also serve as their username.

Users, Passwords, Roles, and Emails

Before you get to the point of creating a user, there’s the typical validation and you have to do: make sure the email field isn’t empty, make sure the email address actually looks like an email address, make sure the email address doesn’t already exist in the system, and so on.

All of that is just standard boilerplate user management code. Assuming that the incoming data passes through your validation, you can kick off the user creation process.

Usually, it amounts to four steps:

  1. Generate the password
  2. Create the user
  3. Set the role
  4. Email the user

Throughout the rest of this article, I’m going to be representing the incoming user email address with $email_address.

Does the user exist?

Before doing anything, make sure that the user account doesn’t already exist. This is really easy to do with the username_exists function.

It accepts the username (or, in our case, the email address) as an argument and returns the ID if the account already exists; null otherwise. You can handle that error accordingly.

if( null == username_exists( $email_address ) ) {

    // More to come...

}

Generate The Password

Assuming that the account doesn’t exist, you want to generate the password. WordPress provides the wp_generate_password function for exactly this.

Though it can accept up to three arguments, I typically tick with the first two – the length of the password to generate and whether or not to include special characters

$password = wp_generate_password( 12, true );

Create The User

Next, I’ll actually create the user profile using wp_create_user which accepts a username, password, and email address, but I’m doubling-up on the email address for the username.

Note also that this function returns the ID of the user (instead of, say, a user object):

$user_id = wp_create_user ( $email_address, $password, $email_address );

Set a Nickname

After that, I like to provide a default nickname for the user. Of course, we really only have the email address but if you’re working with multiple fields or giving users the option to profile their name or some other unique identifier, this is how you’d set their name to display across the site:

wp_update_user(
  array(
    'ID'       => $user_id,
    'nickname' => $email_address
  )
);

You can provide a variety of other information into wp_update_user. At the most basic level, you just need to provide the ID of the user you’re updating.

Once the function fires, the user will be updated.

Set The User’s Role

When new users are created in the application, they need some type of default access to the application. Obviously, this is up you or whatever requirements your project calls for, but for demonstration purposes, I’m giving the user the lowest access – a contributor.

To do this, we need to get an instance of the WP_User object. This is done by passing the ID of the new user into the object’s constructor.

$user = new WP_User( $user_id );

After that, set the value of the role using the set_role method:

$user->set_role( 'contributor' );

Email The New User

All that’s left to do is to shoot the user an email that their account has been created. Email Templates can get really complicated really fast and this is not the article for that.

Here, I’m simply emailing the new user and giving them the password that the was generated by WordPress.

wp_mail( $email_address, 'Welcome!', 'Your password is: ' . $password );

I know, weak email, but you get the idea. There are some subtle nuances when working with this function and I recommend reviewing the notes in the codex on this particular function.

Programmatically Creating a User in WordPress

This is the TL;DR version of the code for those of you that skipped down from the introduction of the article, or that got bored reading everything above:


if( null == username_exists( $email_address ) ) {

  // Generate the password and create the user
  $password = wp_generate_password( 12, false );
  $user_id = wp_create_user( $email_address, $password, $email_address );

  // Set the nickname
  wp_update_user(
    array(
      'ID'          =>    $user_id,
      'nickname'    =>    $email_address
    )
  );

  // Set the role
  $user = new WP_User( $user_id );
  $user->set_role( 'contributor' );

  // Email the user
  wp_mail( $email_address, 'Welcome!', 'Your Password: ' . $password );

} // end if

Resources in the Codex

Although the code above is sufficient for creating a user, I still recommend reviewing each of the Codex articles to make sure you understand exactly what each function accepts, what it returns, and what you can do with it.

There’s much more flexibility availability with the API – I’ve basically presented the simplest case.

43 Comments

Hey, Tom! Great article. Concise, to the point, and descriptive! I have a question for you.

I’m creating a provisioning script that will check and see whether or not a user that is logged into my CAS server has a WordPress account, and if not, will automatically create one with their CAS credentials.

The creator of the CAS plugin I’m using has a script he provided, but it’s for WordPress MU, which is not only old-school (it’s been replaced with WordPress MultiSite and all), but not what I’m looking for.

Now, I’m adapting your script to create a single-install version of the aforementioned script, but herein lies my question: within his script, he is setting up the WordPress environment like so:


// setup the WordPress environment
define( "WP_INSTALLING", true );
require( dirname(__FILE__) . '/wp-load.php' );
require( 'wp-blog-header.php' );
require_once( ABSPATH . WPINC . '/registration.php' );
global $domain, $base;

(I should also mention that the script is run outside of the wpCAS plugin folder in the WordPress root directory; it is called only when CAS can’t find a user in WordPress with credentials matching those within CAS.)

Is this necessary? Do I need to run similar code?

Tom,

I have been looking for WEEKS for a SIMPLE explanation of how to create a user registration page. Most of what I found was too clunky, bloated, complex – in some cases other sites expected that I know all about the codex and missed steps.

You however hit the right medium. Explain the basics and then point to where to get more advanced information.

Thank you very much for this. Now I can use this information as the foundation, build my registration page and then advance from there as my comfort level grows.

Hi Tom,

Thanks for this resource.

I would like to enable contributor to create their own access to their contributor WordPress admin.
It would be great to add this feature on the wp-admin login page.
I will try to use the resources you describe, but I am a real newbie, so it might take me some time. I would appreciate your help so much.

Have a great day!

    Hey Ben – in order to do this, you’d need to go through the process of:

    Creating the user
    Setting the role
    Emailing them their information

    After doing that, you should be good to go with giving them access to the dashboard based on their role.

      Thanks for your reply Tom,

      However what I want to build is a “create your account” link in the login page, so that I don t have to create their accounts.

      Best,

        Hey Ben,

        I wish I could offer more, but something like this falls more in line with a tutorial or “How To” type post rather than a comment. Perhaps this is something that I’ll look into covering in a future post.

Hi Tom:

As always, very helpful post making the whole process clear

Just curious after digging additional resources, is something wrong going straight to the point with wp_insert_user and add data in one step?

Thanks

    Nope! Nothing’s really wrong with going straight to the `wp_insert_user` and adding the data in a single step as long as you and those that come along after you are comfortable reading the code.

    I tend to be verbose in the posts in order to make sure the code is clear.

Tom,

This was immensely helpful!

Thanks!

Todd

Hey thanks a lot for this.

You didn’t happen to write anything similar on the logging in process, did you? I basically just need to redirect people to certain pages that are only available to logged in people after they’ve logged in. I am JUST learning this stuff. I’ve got creating users working now, though!

Thanks in advance for any help.

Tim

    I haven’t written anything specifically about this, but what you can do is write a function that hooks into `wp_head`, then see what the current user role is (once they are logged in).

    If it’s not, say, an administrator, then you can use `wp_redirect` to send them where ever you want them to land.

    Hope this helps!

Hi. You would not know how i can get our software to log the customer in automatically as long as they are logged into our software.

Basically we design bespoke management systems which run on company networks. Within our program they have to login and there credentials are stored on a local database. We are wanting it so that when they login to the software it also logs them into wordpress. Hope that makea sense.

    Without knowing too much more, I’d say you could create a map between the BeSpoke user account and the WordPress user account. When they navigate to the WordPress page, it automatically logins them in with the username and password for said account.

    Check out this function.

Great article Tom!
Tom can you help me how to create a user to wordpress from outside the site i.e from another website(php).

    You’d need to do some pretty involved development to get that to happen. Primarily, you’d have to be able to work with the WordPress API outside or WordPress, or manually connect to the WordPress database and insert all of the information via an SQL query to create the user and all its related records.

Hi Tom, thanks for this article.

I have a website that requires registration for membership access. But I would like to create high converting capture pages and use my Aweber or Mailchimp service. Is there a way to create those capture pages with Aweber or Mailchimp forms that would automatically add users to my wordpress database?

    I’m not really familiar with setting up pages like that using Aweber or Mailchimp; however, once you’ve got the users information, you should be able to send the data to a WordPress site (at least the email address – not the password) to automatically create the user account.

    Perhaps the easiest way to do it is to send the data via query string to the WordPress-powered site.

    Just a suggestion.

Hello. Great post!
You have got one little unnecesary semicolon in TL;DR version of the code in line 12.

Very useful. Thank you for this great article… learnt to create a user programmatically.

Hi,
I love your articles but tried this code as a public static function and received the following error after a long delay of 50-60 seconds:
Fatal error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 130968 bytes) in /path/to/wp-includes/user.php on line 859

This is for WordPress 3.8.1, multisite enabled.
Where should I begin looking for how to solve this issue? I added an ini statement to the php script.

    It’s hard to know without seeing more of the code, but by saying that you’ve added the code as a static function means that it’s in the context of a class.

    And if a class is taking that long to execute a function then there’s perhaps a loop, another function call, or a hook that’s not terminating so PHP is terminating it itself.

    I’d start by commenting out the code responsible for creating the user, supplying some basic output, and then see what the function returns.

Thanks for this tutorial which help me a lot ! There are just few articles which are talking about this.
I needed this tutorial because i have to setup a wordpress intranet for my company and i have to log programmatically users using their window’s login session. So they’ll never have to log via the login page. But it’s tough task as it works ramdomly ! Sometimes i’m logged off and don’t kow why ! Do you have any ideas for thus bug ?

Hey Tom! Great article!

I just wanted to point out also that the majority of the functionality that you outline above is encapsulated in register_new_user function.

Hi,

Thank you for your article.

I have been struggling with what fields to show user on registration form. It seems too complicated to ask user to enter both username and email, both of them need to be unique.

I also thought about username set to email. However, this causes other problems. For example, if your email is email@test.com then:
– user’s nicename will be set to emailtest-com
– user’s display name will be set to email@test.com
leading to exposure of user email on WordPress pages and decreasing site security.

I see two options:
a) generate unique ID at the backend and set both username and nicename to the ID. Ask user for display name
b) ask user for unique name and set the username/nicename to the unique name esp. if you deal with vendors as your users, each having its unique name. display name can be same

What do you think?

Thank you,
Dennis

    Though I agree displaying the username isn’t the most elegant way to show someone’s display name on the frontend of the site, I do disagree that exposing the username is a security risk.

    Regardless, no one wants their email out in the open without explicit consent, right?

    To that end, I recommend just adding a field for selecting a username and/or a display name, performing a check to see if it’s taken before creating a user, and then moving forward from there.

    I hope this helps!

Thanks for the script. I have tried to implement it, but it keeps saying functions don’t exist or “member function get() on a non-object”. Could you please let me know which include files are needed to run this code, as I have not had much luck with guessing the right combination of include files? Thanks!

    Without seeing your code and/or implementation, it’s hard to know why you’re receiving this error.

    Based on the message that you’ve shared, it sounds like you’re calling a method on an object that has yet to be instantiated which could either be your own doing or trying to do so too early in the page lifecycle.

    If you’ve got your hooks setup properly, then it should work as the necessary files will be automatically included.

Very nice. With this code and my adaptations, migrate user’s by CMS to WordPress.
Thanks.

Hi Tom,

Thanks for that simple example with explanation. One question is arising in my head.
The user created by this code is not added in wp-users table, right??

Ya, after adding comment here i got to know it adds in table too.
Thanks a lot for such great example.

Leave a Reply

Name and email address are required. Your email address will not be published.

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>