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.

Category:
Tips
Tags:

Join the conversation! 71 Comments

  1. 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?

  2. 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.

  3. 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!

  4. 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.

  5. Tom,

    This was immensely helpful!

    Thanks!

    Todd

  6. 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

  7. 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.

  8. 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.

  9. 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.

  10. 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.

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

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

  13. 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.

  14. 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 ?

  15. 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.

  16. 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

  17. 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.

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

  19. 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??

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

  21. Hi, I have a ready made script for client management. However, this is standalone registration rather than wordpress. I would like to map/merge/integrate (whatever is) the wordpress registration with the web application, is that possible?

    Ex: When a user register through wordpress, it should automatically create the same login for the web app. Or vise verse.

    The web app creator said they do not support, I’ll have to find my own way to do it. Any help would be thankful.

  22. Hi,

    i’m very new to wordpress and i have to write a plugin that do quite the same thing as yours.

    I’ve tried your code and it works great, but only when i activate the plugin or when i delete a user from the User list… instead i need to make it runs evrey time that a form’s button is clicked.

    I think the problem depends by the add_action() and the trigger passed as argument… but i’m working to it without results.

    So can you give me any advice, please?

    Thanks

    Luca

  23. Hi Tom, nice article. Since you are already using the wp_update_user you might as well set the user_nicename equal to the user ID. All this just to prevent having all your usernames (and in this case, your users’s emails) vulnerable to public access. Wordpres handles by defaul the author page with the url your.domain/author/, so by clicking on an authors name they will know their email adress by just looking at the URL.

    • user_nicename is used to generate permalinks for the site. I supposed you could read this has some type of security risk as giving way the login of the user, but the alternative provided here also gives away the user’s ID which is just as dangerous in a malicious SQL attack.

      Either way, this is just another point to consider so thanks for sharing.

  24. Thanks a lot for the tutorial….

  25. Thanks for this informative article.

    Do you know if there is a way of creating a user such that the first time they visit the site they need to change (well, set) their password?

    many thanks

    :L

  26. Hmmm possibly answering my own question here:

    Seems this might do the trick:

    update_user_option( $user_id, ‘default_password_nag’, true, true );

  27. Thanks, yeah tried it yesterday but it didn’t seem to do anything when I logged in as the new user. Weird.

  28. Excellent Tom, I’ll have a read of that code. Many thanks!

  29. there is a broken link at “If you’re an advanced developer or just want the TL;DR version of this, skip to the code.”

  30. Thank you very much ! Very useful code :)

  31. Thanks. I’m investigating if there’s a way to do this without email using only SMS / verification. I’d like to make the registration as frictionless as possible.

    Step 1 — Get mobile phone / password from user.

    Mobile #:

    Password:

    [Sign Up]

    Step 2 — Create user account with Mobile# as username and makeup some email (remains hidden and never gets emailed)

    Step 3 — Send text message to mobile number with a 4 digit verification number.

    Step 4 — Redirect to verification page for user to verify the 4 digit number they were texted.

    For this to work we’d need to add mobile capable change password that sends a text with a link to their smart phone.

    We could also have a regular profile page for the user to later update (as part of the on-boarding process) to enable normal email communications.

    Any thoughts on this?

    • This is something that can likely be done, though I’ve never implemented it myself. You’d need a third-party service with which to integrate that would be able to relay messages from the phone to your WordPress installation, have the WordPress installation perform the work, then communicate with the third-party service that would intern communicate with the phone again.

      If you’re planning on making a mobile only website, I can see the appeal, but if people will use this on the desktop, I’m not sure I can see why they’d want to do this.

      An alternative might be looking to add authentication using a pre-existing social account like Twitter, Facebook, or Google.

  32. Hi Tom,

    This write up seems very nice.

    We have a sort of ticket plugin on one of our sites, that pipes emails into tickets.

    But it requires a registered user. Instead of removing/changing all the places for the registered. We want to add new users via there incoming email.

    Reading your post, I think we can use that code. As we have an email address.

    My question is, is it required to inform them via email a account has been created? The tickets can be replied to via email and will receive updates via email.

    And if a users email is registered, a reply or new ticket will be created.

    So they don’t really have to be logged in.

    Would it also work without sending that email?

    • This write up seems very nice.

      Thank you!

      Reading your post, I think we can use that code. As we have an email address.

      Do note that this particular code is a bit old so I can’t promise it still works with WordPress 4.6.1, but if it’s changed, it won’t be by much and the code reference will provide everything you need.

      My question is, is it required to inform them via email a account has been created? The tickets can be replied to via email and will receive updates via email.

      I don’t know know if it’s required in that you need to inform them. You can prevent the email from being sent, but ethically, I think it’s important to let them know.

      Would it also work without sending that email?

      As long as the user account is registered with their email address, I don’t see why not.

  33. Thank you so much for sharing.

    The only question I have, mail functionality is not working.

    Any idea what to do to make mail functionality working.

  34. Tom, I would appreciate if you explain why you don’t lock tables.

    It gives 500 Internal Server Error in case if other user is registered the same time.

    Also, I didn’t find any table locking in WordPress code.

    And what are your suggestions for whose who want to maintain this case?

    Thanks.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.