Add methods 'createUser' and 'createUserWithUniqueUsername'

README.md

@@ -56,6 +56,8 @@ Completely framework-agnostic and database-agnostic.
    * [Checking whether the user was "remembered"](#checking-whether-the-user-was-remembered)
    * [IP address](#ip-address)
    * [Additional user information](#additional-user-information)
+ * [Administration (managing users)](administration-managing-users)
+   * [Creating new users](creating-new-users)
  * [Utilities](#utilities)
    * [Creating a random string](#creating-a-random-string)
    * [Creating a UUID v4 as per RFC 4122](#creating-a-uuid-v4-as-per-rfc-4122)
@@ -360,6 +362,35 @@ Here's how to use this library with your own tables for custom user information
     }
     ```
 
+### Administration (managing users)
+
+The administrative interface is available via `$auth->admin()`. You can call various method on this interface, as documented below.
+
+**Warning**: Do *not* forget to implement secure access control before exposing access to this interface. For example, you may provide access to this interface to logged in users with the administrator role only, or use the interface in private scripts only.
+
+#### Creating new users
+
+```php
+try {
+    $userId = $auth->admin()->createUser($_POST['email'], $_POST['password'], $_POST['username']);
+
+    // we have signed up a new user with the ID `$userId`
+}
+catch (\Delight\Auth\InvalidEmailException $e) {
+    // invalid email address
+}
+catch (\Delight\Auth\InvalidPasswordException $e) {
+    // invalid password
+}
+catch (\Delight\Auth\UserAlreadyExistsException $e) {
+    // user already exists
+}
+```
+
+The username in the third parameter is optional. You can pass `null` there if you don't want to manage usernames.
+
+If you want to enforce unique usernames, on the other hand, simply call `createUserWithUniqueUsername` instead of `createUser`, and be prepared to catch the `DuplicateUsernameException`.
+
 ### Utilities
 
 #### Creating a random string

src/Administration.php

@@ -22,6 +22,65 @@ final class Administration extends UserManager {
 		parent::__construct($databaseConnection);
 	}
 
+	/**
+	 * Creates a new user
+	 *
+	 * If you want the user's account to be activated by default, pass `null` as the callback
+	 *
+	 * If you want to make the user verify their email address first, pass an anonymous function as the callback
+	 *
+	 * The callback function must have the following signature:
+	 *
+	 * `function ($selector, $token)`
+	 *
+	 * Both pieces of information must be sent to the user, usually embedded in a link
+	 *
+	 * When the user wants to verify their email address as a next step, both pieces will be required again
+	 *
+	 * @param string $email the email address to register
+	 * @param string $password the password for the new account
+	 * @param string|null $username (optional) the username that will be displayed
+	 * @param callable|null $callback (optional) the function that sends the confirmation email to the user
+	 * @return int the ID of the user that has been created (if any)
+	 * @throws InvalidEmailException if the email address was invalid
+	 * @throws InvalidPasswordException if the password was invalid
+	 * @throws UserAlreadyExistsException if a user with the specified email address already exists
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function createUser($email, $password, $username = null, callable $callback = null) {
+		return $this->createUserInternal(false, $email, $password, $username, $callback);
+	}
+
+	/**
+	 * Creates a new user while ensuring that the username is unique
+	 *
+	 * If you want the user's account to be activated by default, pass `null` as the callback
+	 *
+	 * If you want to make the user verify their email address first, pass an anonymous function as the callback
+	 *
+	 * The callback function must have the following signature:
+	 *
+	 * `function ($selector, $token)`
+	 *
+	 * Both pieces of information must be sent to the user, usually embedded in a link
+	 *
+	 * When the user wants to verify their email address as a next step, both pieces will be required again
+	 *
+	 * @param string $email the email address to register
+	 * @param string $password the password for the new account
+	 * @param string|null $username (optional) the username that will be displayed
+	 * @param callable|null $callback (optional) the function that sends the confirmation email to the user
+	 * @return int the ID of the user that has been created (if any)
+	 * @throws InvalidEmailException if the email address was invalid
+	 * @throws InvalidPasswordException if the password was invalid
+	 * @throws UserAlreadyExistsException if a user with the specified email address already exists
+	 * @throws DuplicateUsernameException if the specified username wasn't unique
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function createUserWithUniqueUsername($email, $password, $username = null, callable $callback = null) {
+		return $this->createUserInternal(true, $email, $password, $username, $callback);
+	}
+
 	protected function throttle($actionType, $customSelector = null) {}
 
 }