Software, Development, and WordPress

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.

71 Comments

  1. Jordan Thornquest

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

    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.

    • Tom McFarlin

      Absolutely dig hearing this, Faxe. Thanks so much for the comment and I’m glad to have helped!

      Good luck with your development efforts :).

  3. Ben

    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!

    • Tom McFarlin

      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.

      • Ben COTTE

        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,

        • Tom McFarlin

          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.

  4. Hugh

    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

    • Tom McFarlin

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

    Tom,

    This was immensely helpful!

    Thanks!

    Todd

  6. Tim Owen

    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

    • Tom McFarlin

      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!

  7. Dean

    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.

    • Tom McFarlin

      Without knowing more about your situation, this is a tough question for me to answer. Sorry.

  8. Dean Hargreaves

    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.

    • Tom McFarlin

      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.

  9. Raju

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

    • Tom McFarlin

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

    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?

    • Tom McFarlin

      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. Dawid Urbański

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

  12. Shasi Kanth

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

  13. LPH

    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.

    • Tom

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

    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 ?

    • Tom

      Off the top of my head, no solution comes to mind primarily because I’m not familiar with that doing that.

      Wish I could be more help!

      • Hathija

        that’s ok but your tutorial helps me a lot ! :)

  15. Tanner Moushey

    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.

    • Tom

      Yes sir – yet another way of doing it. Thanks for adding this to the comments on the post :).

  16. Dennis

    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

    • Tom

      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!

      • Dennis

        Thank you for your thoughts.
        cheers

  17. hamed

    thanks alot

  18. Koa

    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!

    • Tom

      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.

  19. Everaldo Matias

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

  20. Saurabh

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

    • Tom

      It does – wp_update_user adds a single user to the database.

  21. Saurabh

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

  22. Owen

    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.

    • Tom

      Hey Patrick – this question has more to do with the API of the third-party system than with WordPress itself; however, the flow of control would need to be something like this:

      • Once the user has been successfully created in WordPress, an API call is made to the third-party app
      • The app validates the credentials coming from the caller (which, in this case, is WordPress)
      • If it validates, it then creates an account based on that information
      • When the creation is done, an error is either displayed, or success is displayed and they are redirected back to WordPress

      Hope this helps!

  23. luca

    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

    • Tom

      Sorry Luca – without knowing more, it’s hard to offer support on anything else that’s outside the scope of the post.

    • Dawid

      Hi Luca,

      If you want to perform some action on form submit, you should propably use AJAX request.

      If you are not familiar wiht AJAX read this: http://codex.wordpress.org/AJAX

      Using AJAX in wordpress plugin: http://codex.wordpress.org/AJAX_in_Plugins

      After reading both, you should be able to write what you need.

      Regards,

      Dawid.

      • luca

        Thank you, Tom and Dawid, i have studied a little of WordPress Codex and now my plugin works fine. Now i have to focus on generating an url for the activation link of each user that i import form csv, but i’m quite sure it will be easy.

        Thanks and Happy New Year

        Luca

  24. Jorge

    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.

    • Tom

      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.

  25. Dhara Shah

    Thanks a lot for the tutorial….

  26. Luke

    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

  27. Luke

    Hmmm possibly answering my own question here:

    Seems this might do the trick:

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

    • Tom

      There are a couple of ways to do this, but if setting that particular user meta key works, then you’re good to go.

  28. Luke

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

    • Tom

      Your best bet might be to check out the code for Force Password Change. It deals with meta data accomplishes what you’re looking to achieve.

  29. LukeSnarl

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

  30. Mauro Mazzerioli

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

  31. Jess

    Thank you very much ! Very useful code :)

  32. Kevin

    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?

    • Tom

      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.

  33. Tips Kesehatan

    Nice Post!

  34. Martijn

    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?

    • Tom

      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.

  35. Sher Bahadur

    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.

  36. Joey

    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

© 2020 Tom McFarlin

Theme by Anders NorenUp ↑