Add tests for method 'loginWithUsername' in class 'Auth'

README.md

@@ -22,25 +22,46 @@ Completely framework-agnostic and database-agnostic.
 
 ## Installation
 
- * Set up the PHP library
-   * Install via [Composer](https://getcomposer.org/) (recommended)
+ 1. Include the library via [Composer](https://getcomposer.org/):
 
-     `$ composer require delight-im/auth`
+    ```
+    $ composer require delight-im/auth
+    ```
 
-     Include the Composer autoloader:
+ 1. Include the Composer autoloader:
 
-     `require __DIR__.'/vendor/autoload.php';`
+    ```php
+    require __DIR__ . '/vendor/autoload.php';
+    ```
 
-   * or
-   * Install manually
-     * Copy the contents of the [`src`](src) directory to a subfolder of your project
-     * Include the files in your code via `require` or `require_once`
- * Set up a database and create the required tables
-   * [MySQL](Database/MySQL.sql)
+ 1. Set up a database and create the required tables:
+
+    * [MySQL](Database/MySQL.sql)
 
 ## Usage
 
-### Create a new instance
+ * [Creating a new instance](#creating-a-new-instance)
+ * [Registration (sign up)](#registration-sign-up)
+ * [Login (sign in)](#login-sign-in)
+ * [Email verification](#email-verification)
+ * [Keeping the user logged in](#keeping-the-user-logged-in)
+ * [Password reset ("forgot password")](#password-reset-forgot-password)
+ * [Changing the current user's password](#changing-the-current-users-password)
+ * [Logout](#logout)
+ * [Accessing user information](#accessing-user-information)
+   * [Login state](#login-state)
+   * [User ID](#user-id)
+   * [Email address](#email-address)
+   * [Display name](#display-name)
+   * [Checking whether the user was "remembered"](#checking-whether-the-user-was-remembered)
+   * [IP address](#ip-address)
+   * [Additional user information](#additional-user-information)
+ * [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)
+ * [Reading and writing session data](#reading-and-writing-session-data)
+
+### Creating a new instance
 
 ```php
 // $db = new PDO('mysql:dbname=my-database;host=localhost;charset=utf8mb4', 'my-username', 'my-password');
@@ -58,7 +79,7 @@ Only in the very rare case that you need access to your cookies from JavaScript,
 
 If your web server is behind a proxy server and `$_SERVER['REMOTE_ADDR']` only contains the proxy's IP address, you must pass the user's real IP address to the constructor in the fourth argument. The default is `null`.
 
-### Registration (sign up a new user)
+### Registration (sign up)
 
 ```php
 try {
@@ -84,6 +105,8 @@ catch (\Delight\Auth\TooManyRequestsException $e) {
 
 The username in the third parameter is optional. You can pass `null` here if you don't want to manage usernames.
 
+If you want to enforce unique usernames, on the other hand, simply call `registerWithUniqueUsername` instead of `register`, and be prepared to catch the `DuplicateUsernameException`, if necessary.
+
 For email verification, you should build an URL with the selector and token and send it to the user, e.g.:
 
 ```php
@@ -92,7 +115,7 @@ $url = 'https://www.example.com/verify_email?selector='.urlencode($selector).'&t
 
 If you don't want to perform email verification, just omit the last parameter to `Auth#register`. The new user will be active immediately, then.
 
-### Login (sign in an existing user)
+### Login (sign in)
 
 ```php
 try {
@@ -114,6 +137,8 @@ catch (\Delight\Auth\TooManyRequestsException $e) {
 }
 ```
 
+If you want to sign in with usernames on the other hand, either in addition to the login via email address or as a replacement, that's possible as well. Simply call the method `loginWithUsername` instead of method `login`. Then, instead of catching `InvalidEmailException`, make sure to catch both `UnknownUsernameException` and `AmbiguousUsernameException`. You may also want to read the notes about the uniqueness of usernames in the section that explains how to [sign up new users](#registration-sign-up).
+
 ### Email verification
 
 Extract the selector and token from the URL that the user clicked on in the verification email.
@@ -248,7 +273,9 @@ $auth->logout();
 // user has been signed out
 ```
 
-### Checking if the user is signed in
+### Accessing user information
+
+#### Login state
 
 ```php
 if ($auth->isLoggedIn()) {
@@ -261,7 +288,7 @@ else {
 
 A shorthand/alias for this method is `$auth->check()`.
 
-### Getting the user's ID
+#### User ID
 
 ```php
 $id = $auth->getUserId();
@@ -271,7 +298,7 @@ If the user is not currently signed in, this returns `null`.
 
 A shorthand/alias for this method is `$auth->id()`.
 
-### Getting the user's email address
+#### Email address
 
 ```php
 $email = $auth->getEmail();
@@ -279,7 +306,7 @@ $email = $auth->getEmail();
 
 If the user is not currently signed in, this returns `null`.
 
-### Getting the user's display name
+#### Display name
 
 ```php
 $email = $auth->getUsername();
@@ -289,7 +316,7 @@ Remember that usernames are optional and there is only a username if you supplie
 
 If the user is not currently signed in, this returns `null`.
 
-### Checking if the user was "remembered"
+#### Checking whether the user was "remembered"
 
 ```php
 if ($auth->isRemembered()) {
@@ -302,15 +329,36 @@ else {
 
 If the user is not currently signed in, this returns `null`.
 
-### Getting the user's IP address
+#### IP address
 
 ```php
 $ip = $auth->getIpAddress();
 ```
 
-### Reading and writing session data
+#### Additional user information
 
-For detailed information on how to read and write session data conveniently, please refer to [the documentation of the session library](https://github.com/delight-im/PHP-Cookie), which is included by default.
+In order to preserve this library's suitability for all purposes as well as its full re-usability, it doesn't come with additional bundled columns for user information. But you don't have to do without additional user information, of course:
+
+Here's how to use this library with your own tables for custom user information in a maintainable and re-usable way:
+
+ 1. Add any number of custom database tables where you store custom user information, e.g. a table named `profiles`.
+ 1. Whenever you call the `register` method (which returns the new user's ID), add your own logic afterwards that fills your custom database tables.
+ 1. If you need the custom user information only rarely, you may just retrieve it as needed. If you need it more frequently, however, you'd probably want to have it in your session data. The following method is how you can load and access your data in a reliable way:
+
+    ```php
+    function getUserInfo(\Delight\Auth\Auth $auth) {
+        if (!$auth->isLoggedIn()) {
+            return null;
+        }
+
+        if (!isset($_SESSION['_internal_user_info'])) {
+            // TODO: load your custom user information and assign it to the session variable below
+            // $_SESSION['_internal_user_info'] = ...
+        }
+
+        return $_SESSION['_internal_user_info'];
+    }
+    ```
 
 ### Utilities
 
@@ -327,6 +375,10 @@ $randomStr = \Delight\Auth\Auth::createRandomString($length);
 $uuid = \Delight\Auth\Auth::createUuid();
 ```
 
+### Reading and writing session data
+
+For detailed information on how to read and write session data conveniently, please refer to [the documentation of the session library](https://github.com/delight-im/PHP-Cookie#reading-and-writing-session-data), which is included by default.
+
 ## Features
 
  * registration
@@ -372,12 +424,12 @@ This library throws two types of exceptions to indicate problems:
 
 ## General advice
 
- * Both serving the authentication pages (e.g. login and registration) and submitting the data entered by the user should only be done over TLS (HTTPS).
- * You should enforce a minimum length for passwords, e.g. 10 characters, but *no* maximum length. Moreover, you should not restrict the set of allowed characters.
- * Whenever a user was remembered ("remember me") and did not log in by entering their password, you should require re-authentication for critical features.
+ * Serve *all* pages over HTTPS only, i.e. using SSL/TLS for every single request.
+ * You should enforce a minimum length for passwords, e.g. 10 characters, but *never* any maximum length, at least not anywhere below 100 characters. Moreover, you should *not* restrict the set of allowed characters.
+ * Whenever a user was remembered through the "remember me" feature enabled or disabled during sign in, which means that they did not log in by typing their password, you should require re-authentication for critical features.
  * Encourage users to use pass*phrases*, i.e. combinations of words or even full sentences, instead of single pass*words*.
- * Do not prevent users' password managers from working correctly. Thus please use the standard form fields only and do not prevent copy and paste.
- * Before executing sensitive account operations (e.g. changing a user's email address, deleting a user's account), you should always require re-authentication, i.e. require the user to sign in once more.
+ * Do not prevent users' password managers from working correctly. Thus, use the standard form fields only and do not prevent copy and paste.
+ * Before executing sensitive account operations (e.g. changing a user's email address, deleting a user's account), you should always require re-authentication, i.e. require the user to verify their login credentials once more.
  * You should not offer an online password reset feature ("forgot password") for high-security applications.
  * For high-security applications, you should not use email addresses as identifiers. Instead, choose identifiers that are specific to the application and secret, e.g. an internal customer number.
 

src/Auth.php

@@ -151,9 +151,9 @@ class Auth {
 	/**
 	 * Attempts to sign up a user
 	 *
-	 * If you want accounts to be activated by default, pass `null` as the callback
+	 * If you want the user's account to be activated by default, pass `null` as the callback
 	 *
-	 * If you want to perform email verification, pass an anonymous function 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:
 	 *
@@ -174,42 +174,37 @@ class Auth {
 	 * @throws AuthError if an internal problem occurred (do *not* catch)
 	 */
 	public function register($email, $password, $username = null, callable $callback = null) {
-		$this->throttle(self::THROTTLE_ACTION_REGISTER);
+		return $this->createUserInternal(false, $email, $password, $username, $callback);
+	}
 
-		$email = self::validateEmailAddress($email);
-		$password = self::validatePassword($password);
-
-		$username = isset($username) ? trim($username) : null;
-		$password = password_hash($password, PASSWORD_DEFAULT);
-		$verified = isset($callback) && is_callable($callback) ? 0 : 1;
-
-		try {
-			$this->db->insert(
-				'users',
-				[
-					'email' => $email,
-					'password' => $password,
-					'username' => $username,
-					'verified' => $verified,
-					'registered' => time()
-				]
-			);
-		}
-		catch (IntegrityConstraintViolationException $e) {
-			// if we have a duplicate entry
-			throw new UserAlreadyExistsException();
-		}
-		catch (Error $e) {
-			throw new DatabaseError();
-		}
-
-		$newUserId = (int) $this->db->getLastInsertId();
-
-		if ($verified === 0) {
-			$this->createConfirmationRequest($email, $callback);
-		}
-
-		return $newUserId;
+	/**
+	 * Attempts to sign up a 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 registerWithUniqueUsername($email, $password, $username = null, callable $callback = null) {
+		return $this->createUserInternal(true, $email, $password, $username, $callback);
 	}
 
 	/**
@@ -259,7 +254,7 @@ class Auth {
 	}
 
 	/**
-	 * Attempts to sign in a user
+	 * Attempts to sign in a user with their email address and password
 	 *
 	 * @param string $email the user's email address
 	 * @param string $password the user's password
@@ -270,61 +265,27 @@ class Auth {
 	 * @throws AuthError if an internal problem occurred (do *not* catch)
 	 */
 	public function login($email, $password, $rememberDuration = null) {
-		$email = self::validateEmailAddress($email);
-		$password = self::validatePassword($password);
+		$this->authenticateUserInternal($password, $email, null, $rememberDuration);
+	}
 
-		try {
-			$userData = $this->db->selectRow(
-				'SELECT id, password, verified, username FROM users WHERE email = ?',
-				[ $email ]
-			);
-		}
-		catch (Error $e) {
-			throw new DatabaseError();
-		}
-
-		if (!empty($userData)) {
-			if (password_verify($password, $userData['password'])) {
-				// if the password needs to be re-hashed to keep up with improving password cracking techniques
-				if (password_needs_rehash($userData['password'], PASSWORD_DEFAULT)) {
-					// create a new hash from the password and update it in the database
-					$this->updatePassword($userData['id'], $password);
-				}
-
-				if ($userData['verified'] === 1) {
-					$this->onLoginSuccessful($userData['id'], $email, $userData['username'], false);
-
-					// continue to support the old parameter format
-					if ($rememberDuration === true) {
-						$rememberDuration = 60 * 60 * 24 * 28;
-					}
-					elseif ($rememberDuration === false) {
-						$rememberDuration = null;
-					}
-
-					if ($rememberDuration !== null) {
-						$this->createRememberDirective($userData['id'], $rememberDuration);
-					}
-
-					return;
-				}
-				else {
-					throw new EmailNotVerifiedException();
-				}
-			}
-			else {
-				$this->throttle(self::THROTTLE_ACTION_LOGIN);
-				$this->throttle(self::THROTTLE_ACTION_LOGIN, $email);
-
-				throw new InvalidPasswordException();
-			}
-		}
-		else {
-			$this->throttle(self::THROTTLE_ACTION_LOGIN);
-			$this->throttle(self::THROTTLE_ACTION_LOGIN, $email);
-
-			throw new InvalidEmailException();
-		}
+	/**
+	 * Attempts to sign in a user with their username and password
+	 *
+	 * When using this method to authenticate users, you should ensure that usernames are unique
+	 *
+	 * Consistently using {@see registerWithUniqueUsername} instead of {@see register} can be helpful
+	 *
+	 * @param string $username the user's username
+	 * @param string $password the user's password
+	 * @param int|bool|null $rememberDuration (optional) the duration in seconds to keep the user logged in ("remember me"), e.g. `60 * 60 * 24 * 365.25` for one year
+	 * @throws UnknownUsernameException if the specified username does not exist
+	 * @throws AmbiguousUsernameException if the specified username is ambiguous, i.e. there are multiple users with that name
+	 * @throws InvalidPasswordException if the password was invalid
+	 * @throws EmailNotVerifiedException if the email address has not been verified yet via confirmation email
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function loginWithUsername($username, $password, $rememberDuration = null) {
+		$this->authenticateUserInternal($password, null, $username, $rememberDuration);
 	}
 
 	/**
@@ -733,20 +694,228 @@ class Auth {
 		}
 	}
 
+	/**
+	 * 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 bool $requireUniqueUsername whether it must be ensured that the username is unique
+	 * @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 it was specified that the username must be unique while it was *not*
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	private function createUserInternal($requireUniqueUsername, $email, $password, $username = null, callable $callback = null) {
+		$this->throttle(self::THROTTLE_ACTION_REGISTER);
+
+		ignore_user_abort(true);
+
+		$email = self::validateEmailAddress($email);
+		$password = self::validatePassword($password);
+
+		$username = isset($username) ? trim($username) : null;
+
+		// if the supplied username is the empty string or has consisted of whitespace only
+		if ($username === '') {
+			// this actually means that there is no username
+			$username = null;
+		}
+
+		// if the uniqueness of the username is to be ensured
+		if ($requireUniqueUsername) {
+			// if a username has actually been provided
+			if ($username !== null) {
+				// count the number of users who do already have that specified username
+				$occurrencesOfUsername = $this->db->selectValue(
+					'SELECT COUNT(*) FROM users WHERE username = ?',
+					[ $username ]
+				);
+
+				// if any user with that username does already exist
+				if ($occurrencesOfUsername > 0) {
+					// cancel the operation and report the violation of this requirement
+					throw new DuplicateUsernameException();
+				}
+			}
+		}
+
+		$password = password_hash($password, PASSWORD_DEFAULT);
+		$verified = isset($callback) && is_callable($callback) ? 0 : 1;
+
+		try {
+			$this->db->insert(
+				'users',
+				[
+					'email' => $email,
+					'password' => $password,
+					'username' => $username,
+					'verified' => $verified,
+					'registered' => time()
+				]
+			);
+		}
+		catch (IntegrityConstraintViolationException $e) {
+			// if we have a duplicate entry
+			throw new UserAlreadyExistsException();
+		}
+		catch (Error $e) {
+			throw new DatabaseError();
+		}
+
+		$newUserId = (int) $this->db->getLastInsertId();
+
+		if ($verified === 0) {
+			$this->createConfirmationRequest($email, $callback);
+		}
+
+		return $newUserId;
+	}
+
+	/**
+	 * Authenticates an existing user
+	 *
+	 * @param string $password the user's password
+	 * @param string|null $email (optional) the user's email address
+	 * @param string|null $username (optional) the user's username
+	 * @param int|bool|null $rememberDuration (optional) the duration in seconds to keep the user logged in ("remember me"), e.g. `60 * 60 * 24 * 365.25` for one year
+	 * @throws InvalidEmailException if the email address was invalid or could not be found
+	 * @throws UnknownUsernameException if an attempt has been made to authenticate with a non-existing username
+	 * @throws AmbiguousUsernameException if an attempt has been made to authenticate with an ambiguous username
+	 * @throws InvalidPasswordException if the password was invalid
+	 * @throws EmailNotVerifiedException if the email address has not been verified yet via confirmation email
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	private function authenticateUserInternal($password, $email = null, $username = null, $rememberDuration = null) {
+		if ($email !== null) {
+			$email = self::validateEmailAddress($email);
+
+			// attempt to look up the account information using the specified email address
+			try {
+				$userData = $this->getUserDataByEmailAddress(
+					$email,
+					[ 'id', 'email', 'password', 'verified', 'username' ]
+				);
+			}
+			// if there is no user with the specified email address
+			catch (InvalidEmailException $e) {
+				// throttle this operation
+				$this->throttle(self::THROTTLE_ACTION_LOGIN);
+				$this->throttle(self::THROTTLE_ACTION_LOGIN, $email);
+
+				// and re-throw the exception
+				throw new InvalidEmailException();
+			}
+		}
+		elseif ($username !== null) {
+			$username = trim($username);
+
+			// attempt to look up the account information using the specified username
+			try {
+				$userData = $this->getUserDataByUsername(
+					$username,
+					[ 'id', 'email', 'password', 'verified', 'username' ]
+				);
+			}
+			// if there is no user with the specified username
+			catch (UnknownUsernameException $e) {
+				// throttle this operation
+				$this->throttle(self::THROTTLE_ACTION_LOGIN);
+				$this->throttle(self::THROTTLE_ACTION_LOGIN, $username);
+
+				// and re-throw the exception
+				throw new UnknownUsernameException();
+			}
+			// if there are multiple users with the specified username
+			catch (AmbiguousUsernameException $e) {
+				// throttle this operation
+				$this->throttle(self::THROTTLE_ACTION_LOGIN);
+				$this->throttle(self::THROTTLE_ACTION_LOGIN, $username);
+
+				// and re-throw the exception
+				throw new AmbiguousUsernameException();
+			}
+		}
+		// if neither an email address nor a username has been provided
+		else {
+			// we can't do anything here because the method call has been invalid
+			throw new EmailOrUsernameRequiredError();
+		}
+
+		$password = self::validatePassword($password);
+
+		if (password_verify($password, $userData['password'])) {
+			// if the password needs to be re-hashed to keep up with improving password cracking techniques
+			if (password_needs_rehash($userData['password'], PASSWORD_DEFAULT)) {
+				// create a new hash from the password and update it in the database
+				$this->updatePassword($userData['id'], $password);
+			}
+
+			if ($userData['verified'] === 1) {
+				$this->onLoginSuccessful($userData['id'], $userData['email'], $userData['username'], false);
+
+				// continue to support the old parameter format
+				if ($rememberDuration === true) {
+					$rememberDuration = 60 * 60 * 24 * 28;
+				}
+				elseif ($rememberDuration === false) {
+					$rememberDuration = null;
+				}
+
+				if ($rememberDuration !== null) {
+					$this->createRememberDirective($userData['id'], $rememberDuration);
+				}
+
+				return;
+			}
+			else {
+				throw new EmailNotVerifiedException();
+			}
+		}
+		else {
+			// throttle this operation
+			$this->throttle(self::THROTTLE_ACTION_LOGIN);
+			if (isset($email)) {
+				$this->throttle(self::THROTTLE_ACTION_LOGIN, $email);
+			}
+			elseif (isset($username)) {
+				$this->throttle(self::THROTTLE_ACTION_LOGIN, $username);
+			}
+
+			// we cannot authenticate the user due to the password being wrong
+			throw new InvalidPasswordException();
+		}
+	}
+
 	/**
 	 * Returns the requested user data for the account with the specified email address (if any)
 	 *
 	 * You must never pass untrusted input to the parameter that takes the column list
 	 *
 	 * @param string $email the email address to look for
-	 * @param array $requestColumns the columns to request from the user's record
+	 * @param array $requestedColumns the columns to request from the user's record
 	 * @return array the user data (if an account was found)
 	 * @throws InvalidEmailException if the email address could not be found
 	 * @throws AuthError if an internal problem occurred (do *not* catch)
 	 */
-	private function getUserDataByEmailAddress($email, array $requestColumns) {
+	private function getUserDataByEmailAddress($email, array $requestedColumns) {
 		try {
-			$projection = implode(', ', $requestColumns);
+			$projection = implode(', ', $requestedColumns);
 			$userData = $this->db->selectRow(
 				'SELECT ' . $projection . ' FROM users WHERE email = ?',
 				[ $email ]
@@ -764,6 +933,43 @@ class Auth {
 		}
 	}
 
+	/**
+	 * Returns the requested user data for the account with the specified username (if any)
+	 *
+	 * You must never pass untrusted input to the parameter that takes the column list
+	 *
+	 * @param string $username the username to look for
+	 * @param array $requestedColumns the columns to request from the user's record
+	 * @return array the user data (if an account was found unambiguously)
+	 * @throws UnknownUsernameException if no user with the specified username has been found
+	 * @throws AmbiguousUsernameException if multiple users with the specified username have been found
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	private function getUserDataByUsername($username, array $requestedColumns) {
+		try {
+			$projection = implode(', ', $requestedColumns);
+			$users = $this->db->select(
+				'SELECT ' . $projection . ' FROM users WHERE username = ? LIMIT 0, 2',
+				[ $username ]
+			);
+		}
+		catch (Error $e) {
+			throw new DatabaseError();
+		}
+
+		if (empty($users)) {
+			throw new UnknownUsernameException();
+		}
+		else {
+			if (count($users) === 1) {
+				return $users[0];
+			}
+			else {
+				throw new AmbiguousUsernameException();
+			}
+		}
+	}
+
 	/**
 	 * Returns the number of open requests for a password reset by the specified user
 	 *

src/Exceptions.php

@@ -12,6 +12,8 @@ class AuthException extends \Exception {}
 
 class InvalidEmailException extends AuthException {}
 
+class UnknownUsernameException extends AuthException {}
+
 class InvalidPasswordException extends AuthException {}
 
 class EmailNotVerifiedException extends AuthException {}
@@ -26,6 +28,10 @@ class TokenExpiredException extends AuthException {}
 
 class TooManyRequestsException extends AuthException {}
 
+class DuplicateUsernameException extends AuthException {}
+
+class AmbiguousUsernameException extends AuthException {}
+
 class AuthError extends \Exception {}
 
 class DatabaseError extends AuthError {}
@@ -33,3 +39,5 @@ class DatabaseError extends AuthError {}
 class MissingCallbackError extends AuthError {}
 
 class HeadersAlreadySentError extends AuthError {}
+
+class EmailOrUsernameRequiredError extends AuthError {}

tests/index.php

@@ -48,13 +48,27 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 				}
 
 				try {
-					$auth->login($_POST['email'], $_POST['password'], $rememberDuration);
+					if (isset($_POST['email'])) {
+						$auth->login($_POST['email'], $_POST['password'], $rememberDuration);
+					}
+					elseif (isset($_POST['username'])) {
+						$auth->loginWithUsername($_POST['username'], $_POST['password'], $rememberDuration);
+					}
+					else {
+						return 'either email address or username required';
+					}
 
 					return 'ok';
 				}
 				catch (\Delight\Auth\InvalidEmailException $e) {
 					return 'wrong email address';
 				}
+				catch (\Delight\Auth\UnknownUsernameException $e) {
+					return 'unknown username';
+				}
+				catch (\Delight\Auth\AmbiguousUsernameException $e) {
+					return 'ambiguous username';
+				}
 				catch (\Delight\Auth\InvalidPasswordException $e) {
 					return 'wrong password';
 				}
@@ -86,7 +100,16 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 						$callback = null;
 					}
 
-					return $auth->register($_POST['email'], $_POST['password'], $_POST['username'], $callback);
+					if (!isset($_POST['require_unique_username'])) {
+						$_POST['require_unique_username'] = '0';
+					}
+
+					if ($_POST['require_unique_username'] == 0) {
+						return $auth->register($_POST['email'], $_POST['password'], $_POST['username'], $callback);
+					}
+					else {
+						return $auth->registerWithUniqueUsername($_POST['email'], $_POST['password'], $_POST['username'], $callback);
+					}
 				}
 				catch (\Delight\Auth\InvalidEmailException $e) {
 					return 'invalid email address';
@@ -95,7 +118,10 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					return 'invalid password';
 				}
 				catch (\Delight\Auth\UserAlreadyExistsException $e) {
-					return 'user already exists';
+					return 'email address already exists';
+				}
+				catch (\Delight\Auth\DuplicateUsernameException $e) {
+					return 'username already exists';
 				}
 				catch (\Delight\Auth\TooManyRequestsException $e) {
 					return 'too many requests';
@@ -263,7 +289,18 @@ function showGuestUserForm() {
 	echo '<option value="0">Remember (keep logged in)? — No</option>';
 	echo '<option value="1">Remember (keep logged in)? — Yes</option>';
 	echo '</select> ';
-	echo '<button type="submit">Login</button>';
+	echo '<button type="submit">Log in with email address</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="login" />';
+	echo '<input type="text" name="username" placeholder="Username" /> ';
+	echo '<input type="text" name="password" placeholder="Password" /> ';
+	echo '<select name="remember" size="1">';
+	echo '<option value="0">Remember (keep logged in)? — No</option>';
+	echo '<option value="1">Remember (keep logged in)? — Yes</option>';
+	echo '</select> ';
+	echo '<button type="submit">Log in with username</button>';
 	echo '</form>';
 
 	echo '<form action="" method="post" accept-charset="utf-8">';
@@ -275,6 +312,10 @@ function showGuestUserForm() {
 	echo '<option value="0">Require email confirmation? — No</option>';
 	echo '<option value="1">Require email confirmation? — Yes</option>';
 	echo '</select> ';
+	echo '<select name="require_unique_username" size="1">';
+	echo '<option value="0">Username — Any</option>';
+	echo '<option value="1">Username — Unique</option>';
+	echo '</select> ';
 	echo '<button type="submit">Register</button>';
 	echo '</form>';