Move all exceptions and errors to separate files for autoloading

README.md

@@ -55,6 +55,9 @@ Migrating from an earlier version of this project? See our [upgrade guide](Migra
  * [Email verification](#email-verification)
  * [Keeping the user logged in](#keeping-the-user-logged-in)
  * [Password reset (“forgot password”)](#password-reset-forgot-password)
+   * [Initiating the request](#step-1-of-3-initiating-the-request)
+   * [Verifying an attempt](#step-2-of-3-verifying-an-attempt)
+   * [Updating the password](#step-3-of-3-updating-the-password)
  * [Changing the current user’s password](#changing-the-current-users-password)
  * [Changing the current user’s email address](#changing-the-current-users-email-address)
  * [Re-sending confirmation requests](#re-sending-confirmation-requests)
@@ -64,6 +67,7 @@ Migrating from an earlier version of this project? See our [upgrade guide](Migra
    * [User ID](#user-id)
    * [Email address](#email-address)
    * [Display name](#display-name)
+   * [Status information](#status-information)
    * [Checking whether the user was “remembered”](#checking-whether-the-user-was-remembered)
    * [IP address](#ip-address)
    * [Additional user information](#additional-user-information)
@@ -124,34 +128,46 @@ During development, you may want to disable the request limiting or throttling p
 
 During the lifetime of a session, some user data may be changed remotely, either by a client in another session or by an administrator. That means this information must be regularly resynchronized with its authoritative source in the database, which this library does automatically. By default, this happens every five minutes. If you want to change this interval, pass a custom interval in seconds to the constructor as the fifth argument, which is named `$sessionResyncInterval`.
 
+If all your database tables need a common database name, schema name, or other qualifier that must be specified explicitly, you can optionally pass that qualifier to the constructor as the sixth parameter, which is named `$dbSchema`.
+
 ### Registration (sign up)
 
 ```php
 try {
     $userId = $auth->register($_POST['email'], $_POST['password'], $_POST['username'], function ($selector, $token) {
-        // send `$selector` and `$token` to the user (e.g. via email)
+        echo 'Send ' . $selector . ' and ' . $token . ' to the user (e.g. via email)';
     });
 
-    // we have signed up a new user with the ID `$userId`
+    echo 'We have signed up a new user with the ID ' . $userId;
 }
 catch (\Delight\Auth\InvalidEmailException $e) {
-    // invalid email address
+    die('Invalid email address');
 }
 catch (\Delight\Auth\InvalidPasswordException $e) {
-    // invalid password
+    die('Invalid password');
 }
 catch (\Delight\Auth\UserAlreadyExistsException $e) {
-    // user already exists
+    die('User already exists');
 }
 catch (\Delight\Auth\TooManyRequestsException $e) {
-    // too many requests
+    die('Too many requests');
 }
 ```
 
+**Note:** The anonymous callback function is a [closure](http://php.net/manual/en/functions.anonymous.php). Thus, besides its own parameters, only [superglobals](http://php.net/manual/en/language.variables.superglobals.php) like `$_GET`, `$_POST`, `$_COOKIE` and `$_SERVER` are available inside. For any other variable from the parent scope, you need to explicitly make a copy available inside by adding a `use` clause after the parameter list.
+
 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 `registerWithUniqueUsername` instead of `register`, and be prepared to catch the `DuplicateUsernameException`.
 
+**Note:** When accepting and managing usernames, you may want to exclude non-printing control characters and certain printable special characters, as in the character class `[\x00-\x1f\x7f\/:\\]`. In order to do so, you could wrap the call to `Auth#register` or `Auth#registerWithUniqueUsername` inside a conditional branch, for example by only accepting usernames when the following condition is satisfied:
+
+```php
+if (\preg_match('/[\x00-\x1f\x7f\/:\\\\]/', $username) === 0) {
+    // ...
+}
+```
+
 For email verification, you should build an URL with the selector and token and send it to the user, e.g.:
 
 ```php
@@ -160,25 +176,29 @@ $url = 'https://www.example.com/verify_email?selector=' . \urlencode($selector)
 
 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.
 
+Need to store additional user information? Read on [here](#additional-user-information).
+
+**Note:** When sending an email to the user, please note that the (optional) username, at this point, has not yet been confirmed as acceptable to the owner of the (new) email address. It could contain offensive or misleading language chosen by someone who is not actually the owner of the address.
+
 ### Login (sign in)
 
 ```php
 try {
     $auth->login($_POST['email'], $_POST['password']);
 
-    // user is logged in
+    echo 'User is logged in';
 }
 catch (\Delight\Auth\InvalidEmailException $e) {
-    // wrong email address
+    die('Wrong email address');
 }
 catch (\Delight\Auth\InvalidPasswordException $e) {
-    // wrong password
+    die('Wrong password');
 }
 catch (\Delight\Auth\EmailNotVerifiedException $e) {
-    // email not verified
+    die('Email not verified');
 }
 catch (\Delight\Auth\TooManyRequestsException $e) {
-    // too many requests
+    die('Too many requests');
 }
 ```
 
@@ -192,24 +212,26 @@ Extract the selector and token from the URL that the user clicked on in the veri
 try {
     $auth->confirmEmail($_GET['selector'], $_GET['token']);
 
-    // email address has been verified
+    echo 'Email address has been verified';
 }
 catch (\Delight\Auth\InvalidSelectorTokenPairException $e) {
-    // invalid token
+    die('Invalid token');
 }
 catch (\Delight\Auth\TokenExpiredException $e) {
-    // token expired
+    die('Token expired');
 }
 catch (\Delight\Auth\UserAlreadyExistsException $e) {
-    // email address already exists
+    die('Email address already exists');
 }
 catch (\Delight\Auth\TooManyRequestsException $e) {
-    // too many requests
+    die('Too many requests');
 }
 ```
 
 If you want the user to be automatically signed in after successful confirmation, just call `confirmEmailAndSignIn` instead of `confirmEmail`. That alternative method also supports [persistent logins](#keeping-the-user-logged-in) via its optional third parameter.
 
+On success, the two methods `confirmEmail` and `confirmEmailAndSignIn` both return an array with the user’s new email address, which has just been verified, at index one. If the confirmation was for an address change instead of a simple address verification, the user’s old email address will be included in the array at index zero.
+
 ### Keeping the user logged in
 
 The third parameter to the `Auth#login` and `Auth#confirmEmailAndSignIn` methods controls whether the login is persistent with a long-lived cookie. With such a persistent login, users may stay authenticated for a long time, even when the browser session has already been closed and the session cookies have expired. Typically, you’ll want to keep the user logged in for weeks or months with this feature, which is known as “remember me” or “keep me logged in”. Many users will find this more convenient, but it may be less secure if they leave their devices unattended.
@@ -242,31 +264,35 @@ Omit the third parameter or set it to `null` to disable the feature. Otherwise,
 ```php
 try {
     $auth->forgotPassword($_POST['email'], function ($selector, $token) {
-        // send `$selector` and `$token` to the user (e.g. via email)
+        echo 'Send ' . $selector . ' and ' . $token . ' to the user (e.g. via email)';
     });
 
-    // request has been generated
+    echo 'Request has been generated';
 }
 catch (\Delight\Auth\InvalidEmailException $e) {
-    // invalid email address
+    die('Invalid email address');
 }
 catch (\Delight\Auth\EmailNotVerifiedException $e) {
-    // email not verified
+    die('Email not verified');
 }
 catch (\Delight\Auth\ResetDisabledException $e) {
-    // password reset is disabled
+    die('Password reset is disabled');
 }
 catch (\Delight\Auth\TooManyRequestsException $e) {
-    // too many requests
+    die('Too many requests');
 }
 ```
 
+**Note:** The anonymous callback function is a [closure](http://php.net/manual/en/functions.anonymous.php). Thus, besides its own parameters, only [superglobals](http://php.net/manual/en/language.variables.superglobals.php) like `$_GET`, `$_POST`, `$_COOKIE` and `$_SERVER` are available inside. For any other variable from the parent scope, you need to explicitly make a copy available inside by adding a `use` clause after the parameter list.
+
 You should build an URL with the selector and token and send it to the user, e.g.:
 
 ```php
 $url = 'https://www.example.com/reset_password?selector=' . \urlencode($selector) . '&token=' . \urlencode($token);
 ```
 
+If the default lifetime of the password reset requests does not work for you, you can use the third parameter of `Auth#forgotPassword` to specify a custom interval in seconds after which the requests should expire.
+
 #### Step 2 of 3: Verifying an attempt
 
 As the next step, users will click on the link that they received. Extract the selector and token from the URL.
@@ -277,22 +303,22 @@ If the selector/token pair is valid, let the user choose a new password:
 try {
     $auth->canResetPasswordOrThrow($_GET['selector'], $_GET['token']);
 
-    // put the selector into a `hidden` field (or keep it in the URL)
-    // put the token into a `hidden` field (or keep it in the URL)
+    echo 'Put the selector into a "hidden" field (or keep it in the URL)';
+    echo 'Put the token into a "hidden" field (or keep it in the URL)';
 
-    // ask the user for their new password
+    echo 'Ask the user for their new password';
 }
 catch (\Delight\Auth\InvalidSelectorTokenPairException $e) {
-    // invalid token
+    die('Invalid token');
 }
 catch (\Delight\Auth\TokenExpiredException $e) {
-    // token expired
+    die('Token expired');
 }
 catch (\Delight\Auth\ResetDisabledException $e) {
-    // password reset is disabled
+    die('Password reset is disabled');
 }
 catch (\Delight\Auth\TooManyRequestsException $e) {
-    // too many requests
+    die('Too many requests');
 }
 ```
 
@@ -300,10 +326,10 @@ Alternatively, if you don’t need any error messages but only want to check the
 
 ```php
 if ($auth->canResetPassword($_GET['selector'], $_GET['token'])) {
-    // put the selector into a `hidden` field (or keep it in the URL)
-    // put the token into a `hidden` field (or keep it in the URL)
+    echo 'Put the selector into a "hidden" field (or keep it in the URL)';
+    echo 'Put the token into a "hidden" field (or keep it in the URL)';
 
-    // ask the user for their new password
+    echo 'Ask the user for their new password';
 }
 ```
 
@@ -315,25 +341,29 @@ Now when you have the new password for the user (and still have the other two pi
 try {
     $auth->resetPassword($_POST['selector'], $_POST['token'], $_POST['password']);
 
-    // password has been reset
+    echo 'Password has been reset';
 }
 catch (\Delight\Auth\InvalidSelectorTokenPairException $e) {
-    // invalid token
+    die('Invalid token');
 }
 catch (\Delight\Auth\TokenExpiredException $e) {
-    // token expired
+    die('Token expired');
 }
 catch (\Delight\Auth\ResetDisabledException $e) {
-    // password reset is disabled
+    die('Password reset is disabled');
 }
 catch (\Delight\Auth\InvalidPasswordException $e) {
-    // invalid password
+    die('Invalid password');
 }
 catch (\Delight\Auth\TooManyRequestsException $e) {
-    // too many requests
+    die('Too many requests');
 }
 ```
 
+Do you want to have the respective user signed in automatically when their password reset succeeds? Simply use `Auth#resetPasswordAndSignIn` instead of `Auth#resetPassword` to log in the user immediately.
+
+If you need the user’s ID or email address, e.g. for sending them a notification that their password has successfully been reset, just use the return value of `Auth#resetPassword`, which is an array containing two entries named `id` and `email`.
+
 ### Changing the current user’s password
 
 If a user is currently logged in, they may change their password.
@@ -342,16 +372,16 @@ If a user is currently logged in, they may change their password.
 try {
     $auth->changePassword($_POST['oldPassword'], $_POST['newPassword']);
 
-    // password has been changed
+    echo 'Password has been changed';
 }
 catch (\Delight\Auth\NotLoggedInException $e) {
-    // not logged in
+    die('Not logged in');
 }
 catch (\Delight\Auth\InvalidPasswordException $e) {
-    // invalid password(s)
+    die('Invalid password(s)');
 }
 catch (\Delight\Auth\TooManyRequestsException $e) {
-    // too many requests
+    die('Too many requests');
 }
 ```
 
@@ -369,38 +399,42 @@ If a user is currently logged in, they may change their email address.
 try {
     if ($auth->reconfirmPassword($_POST['password'])) {
         $auth->changeEmail($_POST['newEmail'], function ($selector, $token) {
-            // send `$selector` and `$token` to the user (e.g. via email to the *new* address)
+            echo 'Send ' . $selector . ' and ' . $token . ' to the user (e.g. via email to the *new* address)';
         });
 
-        // the change will take effect as soon as the new email address has been confirmed
+        echo 'The change will take effect as soon as the new email address has been confirmed';
     }
     else {
-        // we can't say if the user is who they claim to be
+        echo 'We can\'t say if the user is who they claim to be';
     }
 }
 catch (\Delight\Auth\InvalidEmailException $e) {
-    // invalid email address
+    die('Invalid email address');
 }
 catch (\Delight\Auth\UserAlreadyExistsException $e) {
-    // email address already exists
+    die('Email address already exists');
 }
 catch (\Delight\Auth\EmailNotVerifiedException $e) {
-    // account not verified
+    die('Account not verified');
 }
 catch (\Delight\Auth\NotLoggedInException $e) {
-    // not logged in
+    die('Not logged in');
 }
 catch (\Delight\Auth\TooManyRequestsException $e) {
-    // too many requests
+    die('Too many requests');
 }
 ```
 
+**Note:** The anonymous callback function is a [closure](http://php.net/manual/en/functions.anonymous.php). Thus, besides its own parameters, only [superglobals](http://php.net/manual/en/language.variables.superglobals.php) like `$_GET`, `$_POST`, `$_COOKIE` and `$_SERVER` are available inside. For any other variable from the parent scope, you need to explicitly make a copy available inside by adding a `use` clause after the parameter list.
+
 For email verification, you should build an URL with the selector and token and send it to the user, e.g.:
 
 ```php
 $url = 'https://www.example.com/verify_email?selector=' . \urlencode($selector) . '&token=' . \urlencode($token);
 ```
 
+**Note:** When sending an email to the user, please note that the (optional) username, at this point, has not yet been confirmed as acceptable to the owner of the (new) email address. It could contain offensive or misleading language chosen by someone who is not actually the owner of the address.
+
 After the request to change the email address has been made, or even better, after the change has been confirmed by the user, you should send an email to their account’s *previous* email address as an out-of-band notification informing the account owner about this critical change.
 
 **Note:** Changes to a user’s email address take effect in the local session immediately, as expected. In other sessions (e.g. on other devices), the changes may need up to five minutes to take effect, though. This increases performance and usually poses no problem. If you want to change this behavior, nevertheless, simply decrease (or perhaps increase) the value that you pass to the [`Auth` constructor](#creating-a-new-instance) as the argument named `$sessionResyncInterval`.
@@ -412,16 +446,16 @@ If an earlier confirmation request could not be delivered to the user, or if the
 ```php
 try {
     $auth->resendConfirmationForEmail($_POST['email'], function ($selector, $token) {
-        // send `$selector` and `$token` to the user (e.g. via email)
+        echo 'Send ' . $selector . ' and ' . $token . ' to the user (e.g. via email)';
     });
 
-    // the user may now respond to the confirmation request (usually by clicking a link)
+    echo 'The user may now respond to the confirmation request (usually by clicking a link)';
 }
 catch (\Delight\Auth\ConfirmationRequestNotFound $e) {
-    // no earlier request found that could be re-sent
+    die('No earlier request found that could be re-sent');
 }
 catch (\Delight\Auth\TooManyRequestsException $e) {
-    // there have been too many requests -- try again later
+    die('There have been too many requests -- try again later');
 }
 ```
 
@@ -430,25 +464,29 @@ If you want to specify the user by their ID instead of by their email address, t
 ```php
 try {
     $auth->resendConfirmationForUserId($_POST['userId'], function ($selector, $token) {
-        // send `$selector` and `$token` to the user (e.g. via email)
+        echo 'Send ' . $selector . ' and ' . $token . ' to the user (e.g. via email)';
     });
 
-    // the user may now respond to the confirmation request (usually by clicking a link)
+    echo 'The user may now respond to the confirmation request (usually by clicking a link)';
 }
 catch (\Delight\Auth\ConfirmationRequestNotFound $e) {
-    // no earlier request found that could be re-sent
+    die('No earlier request found that could be re-sent');
 }
 catch (\Delight\Auth\TooManyRequestsException $e) {
-    // there have been too many requests -- try again later
+    die('There have been too many requests -- try again later');
 }
 ```
 
+**Note:** The anonymous callback function is a [closure](http://php.net/manual/en/functions.anonymous.php). Thus, besides its own parameters, only [superglobals](http://php.net/manual/en/language.variables.superglobals.php) like `$_GET`, `$_POST`, `$_COOKIE` and `$_SERVER` are available inside. For any other variable from the parent scope, you need to explicitly make a copy available inside by adding a `use` clause after the parameter list.
+
 Usually, you should build an URL with the selector and token and send it to the user, e.g. as follows:
 
 ```php
 $url = 'https://www.example.com/verify_email?selector=' . \urlencode($selector) . '&token=' . \urlencode($token);
 ```
 
+**Note:** When sending an email to the user, please note that the (optional) username, at this point, has not yet been confirmed as acceptable to the owner of the (new) email address. It could contain offensive or misleading language chosen by someone who is not actually the owner of the address.
+
 ### Logout
 
 ```php
@@ -460,7 +498,7 @@ try {
     $auth->logOutEverywhereElse();
 }
 catch (\Delight\Auth\NotLoggedInException $e) {
-    // not logged in
+    die('Not logged in');
 }
 
 // or
@@ -469,7 +507,7 @@ try {
     $auth->logOutEverywhere();
 }
 catch (\Delight\Auth\NotLoggedInException $e) {
-    // not logged in
+    die('Not logged in');
 }
 ```
 
@@ -487,10 +525,10 @@ $auth->destroySession();
 
 ```php
 if ($auth->isLoggedIn()) {
-    // user is signed in
+    echo 'User is signed in';
 }
 else {
-    // user is *not* signed in yet
+    echo 'User is not signed in yet';
 }
 ```
 
@@ -517,7 +555,7 @@ If the user is not currently signed in, this returns `null`.
 #### Display name
 
 ```php
-$email = $auth->getUsername();
+$username = $auth->getUsername();
 ```
 
 Remember that usernames are optional and there is only a username if you supplied it during registration.
@@ -528,27 +566,27 @@ If the user is not currently signed in, this returns `null`.
 
 ```php
 if ($auth->isNormal()) {
-    // user is in default state
+    echo 'User is in default state';
 }
 
 if ($auth->isArchived()) {
-    // user has been archived
+    echo 'User has been archived';
 }
 
 if ($auth->isBanned()) {
-    // user has been banned
+    echo 'User has been banned';
 }
 
 if ($auth->isLocked()) {
-    // user has been locked
+    echo 'User has been locked';
 }
 
 if ($auth->isPendingReview()) {
-    // user is pending review
+    echo 'User is pending review';
 }
 
 if ($auth->isSuspended()) {
-    // user has been suspended
+    echo 'User has been suspended';
 }
 ```
 
@@ -556,10 +594,10 @@ if ($auth->isSuspended()) {
 
 ```php
 if ($auth->isRemembered()) {
-    // user did not sign in but was logged in through their long-lived cookie
+    echo 'User did not sign in but was logged in through their long-lived cookie';
 }
 else {
-    // user signed in manually
+    echo 'User signed in manually';
 }
 ```
 
@@ -605,17 +643,17 @@ For example, when a user has been remembered by a long-lived cookie and thus `Au
 ```php
 try {
     if ($auth->reconfirmPassword($_POST['password'])) {
-        // the user really seems to be who they claim to be
+        echo 'The user really seems to be who they claim to be';
     }
     else {
-        // we can't say if the user is who they claim to be
+        echo 'We can\'t say if the user is who they claim to be';
     }
 }
 catch (\Delight\Auth\NotLoggedInException $e) {
-    // the user is not signed in
+    die('The user is not signed in');
 }
 catch (\Delight\Auth\TooManyRequestsException $e) {
-    // too many requests
+    die('Too many requests');
 }
 ```
 
@@ -629,19 +667,19 @@ Users may have no role at all (which they do by default), exactly one role, or a
 
 ```php
 if ($auth->hasRole(\Delight\Auth\Role::SUPER_MODERATOR)) {
-    // the user is a super moderator
+    echo 'The user is a super moderator';
 }
 
 // or
 
 if ($auth->hasAnyRole(\Delight\Auth\Role::DEVELOPER, \Delight\Auth\Role::MANAGER)) {
-    // the user is either a developer, or a manager, or both
+    echo 'The user is either a developer, or a manager, or both';
 }
 
 // or
 
 if ($auth->hasAllRoles(\Delight\Auth\Role::DEVELOPER, \Delight\Auth\Role::MANAGER)) {
-    // the user is both a developer and a manager
+    echo 'The user is both a developer and a manager';
 }
 ```
 
@@ -708,20 +746,20 @@ function canEditArticle(\Delight\Auth\Auth $auth) {
 
 // ...
 
-if (canEditArticle($app->auth())) {
-    // the user can edit articles here
+if (canEditArticle($auth)) {
+    echo 'The user can edit articles here';
 }
 
 // ...
 
-if (canEditArticle($app->auth())) {
-    // ... and here
+if (canEditArticle($auth)) {
+    echo '... and here';
 }
 
 // ...
 
-if (canEditArticle($app->auth())) {
-    // ... and here
+if (canEditArticle($auth)) {
+    echo '... and here';
 }
 ```
 
@@ -777,17 +815,17 @@ try {
     if ($auth->reconfirmPassword($_POST['password'])) {
         $auth->setPasswordResetEnabled($_POST['enabled'] == 1);
 
-        // the setting has been changed
+        echo 'The setting has been changed';
     }
     else {
-        // we can't say if the user is who they claim to be
+        echo 'We can\'t say if the user is who they claim to be';
     }
 }
 catch (\Delight\Auth\NotLoggedInException $e) {
-    // the user is not signed in
+    die('The user is not signed in');
 }
 catch (\Delight\Auth\TooManyRequestsException $e) {
-    // too many requests
+    die('Too many requests');
 }
 ```
 
@@ -810,7 +848,7 @@ try {
     // throttle the specified resource or feature to *3* requests per *60* seconds
     $auth->throttle([ 'my-resource-name' ], 3, 60);
 
-    // do something with the resource or feature
+    echo 'Do something with the resource or feature';
 }
 catch (\Delight\Auth\TooManyRequestsException $e) {
     // operation cancelled
@@ -844,16 +882,16 @@ Do not forget to implement secure access control before exposing access to this
 try {
     $userId = $auth->admin()->createUser($_POST['email'], $_POST['password'], $_POST['username']);
 
-    // we have signed up a new user with the ID `$userId`
+    echo 'We have signed up a new user with the ID ' . $userId;
 }
 catch (\Delight\Auth\InvalidEmailException $e) {
-    // invalid email address
+    die('Invalid email address');
 }
 catch (\Delight\Auth\InvalidPasswordException $e) {
-    // invalid password
+    die('Invalid password');
 }
 catch (\Delight\Auth\UserAlreadyExistsException $e) {
-    // user already exists
+    die('User already exists');
 }
 ```
 
@@ -870,7 +908,7 @@ try {
     $auth->admin()->deleteUserById($_POST['id']);
 }
 catch (\Delight\Auth\UnknownIdException $e) {
-    // unknown ID
+    die('Unknown ID');
 }
 ```
 
@@ -881,7 +919,7 @@ try {
     $auth->admin()->deleteUserByEmail($_POST['email']);
 }
 catch (\Delight\Auth\InvalidEmailException $e) {
-    // unknown email address
+    die('Unknown email address');
 }
 ```
 
@@ -892,13 +930,23 @@ try {
     $auth->admin()->deleteUserByUsername($_POST['username']);
 }
 catch (\Delight\Auth\UnknownUsernameException $e) {
-    // unknown username
+    die('Unknown username');
 }
 catch (\Delight\Auth\AmbiguousUsernameException $e) {
-    // ambiguous username
+    die('Ambiguous username');
 }
 ```
 
+#### Retrieving a list of registered users
+
+When fetching a list of all users, the requirements vary greatly between projects and use cases, and customization is common. For example, you might want to fetch different columns, join related tables, filter by certain criteria, change how results are sorted (in varying direction), and limit the number of results (while providing an offset).
+
+That’s why it’s easier to use a single custom SQL query. Start with the following:
+
+```sql
+SELECT id, email, username, status, verified, roles_mask, registered, last_login FROM users;
+```
+
 #### Assigning roles to users
 
 ```php
@@ -906,7 +954,7 @@ try {
     $auth->admin()->addRoleForUserById($userId, \Delight\Auth\Role::ADMIN);
 }
 catch (\Delight\Auth\UnknownIdException $e) {
-    // unknown user ID
+    die('Unknown user ID');
 }
 
 // or
@@ -915,7 +963,7 @@ try {
     $auth->admin()->addRoleForUserByEmail($userEmail, \Delight\Auth\Role::ADMIN);
 }
 catch (\Delight\Auth\InvalidEmailException $e) {
-    // unknown email address
+    die('Unknown email address');
 }
 
 // or
@@ -924,14 +972,14 @@ try {
     $auth->admin()->addRoleForUserByUsername($username, \Delight\Auth\Role::ADMIN);
 }
 catch (\Delight\Auth\UnknownUsernameException $e) {
-    // unknown username
+    die('Unknown username');
 }
 catch (\Delight\Auth\AmbiguousUsernameException $e) {
-    // ambiguous username
+    die('Ambiguous username');
 }
 ```
 
-**Note:** Changes to a user’s set of roles take effect in the local session immediately, as expected. In other sessions (e.g. on other devices), the changes may need up to five minutes to take effect, though. This increases performance and usually poses no problem. If you want to change this behavior, nevertheless, simply decrease (or perhaps increase) the value that you pass to the [`Auth` constructor](#creating-a-new-instance) as the argument named `$sessionResyncInterval`.
+**Note:** Changes to a user’s set of roles may need up to five minutes to take effect. This increases performance and usually poses no problem. If you want to change this behavior, nevertheless, simply decrease (or perhaps increase) the value that you pass to the [`Auth` constructor](#creating-a-new-instance) as the argument named `$sessionResyncInterval`.
 
 #### Taking roles away from users
 
@@ -940,7 +988,7 @@ try {
     $auth->admin()->removeRoleForUserById($userId, \Delight\Auth\Role::ADMIN);
 }
 catch (\Delight\Auth\UnknownIdException $e) {
-    // unknown user ID
+    die('Unknown user ID');
 }
 
 // or
@@ -949,7 +997,7 @@ try {
     $auth->admin()->removeRoleForUserByEmail($userEmail, \Delight\Auth\Role::ADMIN);
 }
 catch (\Delight\Auth\InvalidEmailException $e) {
-    // unknown email address
+    die('Unknown email address');
 }
 
 // or
@@ -958,28 +1006,28 @@ try {
     $auth->admin()->removeRoleForUserByUsername($username, \Delight\Auth\Role::ADMIN);
 }
 catch (\Delight\Auth\UnknownUsernameException $e) {
-    // unknown username
+    die('Unknown username');
 }
 catch (\Delight\Auth\AmbiguousUsernameException $e) {
-    // ambiguous username
+    die('Ambiguous username');
 }
 ```
 
-**Note:** Changes to a user’s set of roles take effect in the local session immediately, as expected. In other sessions (e.g. on other devices), the changes may need up to five minutes to take effect, though. This increases performance and usually poses no problem. If you want to change this behavior, nevertheless, simply decrease (or perhaps increase) the value that you pass to the [`Auth` constructor](#creating-a-new-instance) as the argument named `$sessionResyncInterval`.
+**Note:** Changes to a user’s set of roles may need up to five minutes to take effect. This increases performance and usually poses no problem. If you want to change this behavior, nevertheless, simply decrease (or perhaps increase) the value that you pass to the [`Auth` constructor](#creating-a-new-instance) as the argument named `$sessionResyncInterval`.
 
 #### Checking roles
 
 ```php
 try {
     if ($auth->admin()->doesUserHaveRole($userId, \Delight\Auth\Role::ADMIN)) {
-        // the specified user is an administrator
+        echo 'The specified user is an administrator';
     }
     else {
-        // the specified user is *not* an administrator
+        echo 'The specified user is not an administrator';
     }
 }
 catch (\Delight\Auth\UnknownIdException $e) {
-    // unknown user ID
+    die('Unknown user ID');
 }
 ```
 
@@ -996,10 +1044,10 @@ try {
     $auth->admin()->logInAsUserById($_POST['id']);
 }
 catch (\Delight\Auth\UnknownIdException $e) {
-    // unknown ID
+    die('Unknown ID');
 }
 catch (\Delight\Auth\EmailNotVerifiedException $e) {
-    // email address not verified
+    die('Email address not verified');
 }
 
 // or
@@ -1008,10 +1056,10 @@ try {
     $auth->admin()->logInAsUserByEmail($_POST['email']);
 }
 catch (\Delight\Auth\InvalidEmailException $e) {
-    // unknown email address
+    die('Unknown email address');
 }
 catch (\Delight\Auth\EmailNotVerifiedException $e) {
-    // email address not verified
+    die('Email address not verified');
 }
 
 // or
@@ -1020,13 +1068,13 @@ try {
     $auth->admin()->logInAsUserByUsername($_POST['username']);
 }
 catch (\Delight\Auth\UnknownUsernameException $e) {
-    // unknown username
+    die('Unknown username');
 }
 catch (\Delight\Auth\AmbiguousUsernameException $e) {
-    // ambiguous username
+    die('Ambiguous username');
 }
 catch (\Delight\Auth\EmailNotVerifiedException $e) {
-    // email address not verified
+    die('Email address not verified');
 }
 ```
 
@@ -1037,10 +1085,10 @@ try {
     $auth->admin()->changePasswordForUserById($_POST['id'], $_POST['newPassword']);
 }
 catch (\Delight\Auth\UnknownIdException $e) {
-    // unknown ID
+    die('Unknown ID');
 }
 catch (\Delight\Auth\InvalidPasswordException $e) {
-    // invalid password
+    die('Invalid password');
 }
 
 // or
@@ -1049,13 +1097,13 @@ try {
     $auth->admin()->changePasswordForUserByUsername($_POST['username'], $_POST['newPassword']);
 }
 catch (\Delight\Auth\UnknownUsernameException $e) {
-    // unknown username
+    die('Unknown username');
 }
 catch (\Delight\Auth\AmbiguousUsernameException $e) {
-    // ambiguous username
+    die('Ambiguous username');
 }
 catch (\Delight\Auth\InvalidPasswordException $e) {
-    // invalid password
+    die('Invalid password');
 }
 ```
 

composer.json

@@ -6,7 +6,7 @@
 		"ext-openssl": "*",
 		"delight-im/base64": "^1.0",
 		"delight-im/cookie": "^3.1",
-		"delight-im/db": "^1.2"
+		"delight-im/db": "^1.3"
 	},
 	"type": "library",
 	"keywords": [ "auth", "authentication", "login", "security" ],

composer.lock

@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file",
         "This file is @generated automatically"
     ],
-    "content-hash": "54d541ae3c5ba25b0cc06688d2b65467",
+    "content-hash": "e4acd9e4ba13c4d0692f07a03a454859",
     "packages": [
         {
             "name": "delight-im/base64",
@@ -90,16 +90,16 @@
         },
         {
             "name": "delight-im/db",
-            "version": "v1.2.0",
+            "version": "v1.3.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/delight-im/PHP-DB.git",
-                "reference": "df99ef7c2e86c7ce206647ffe8ba74447c075b57"
+                "reference": "7a03da20b5592fa445c10cd6c7245d51037292c4"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/delight-im/PHP-DB/zipball/df99ef7c2e86c7ce206647ffe8ba74447c075b57",
-                "reference": "df99ef7c2e86c7ce206647ffe8ba74447c075b57",
+                "url": "https://api.github.com/repos/delight-im/PHP-DB/zipball/7a03da20b5592fa445c10cd6c7245d51037292c4",
+                "reference": "7a03da20b5592fa445c10cd6c7245d51037292c4",
                 "shasum": ""
             },
             "require": {
@@ -127,7 +127,7 @@
                 "sql",
                 "sqlite"
             ],
-            "time": "2017-03-18T20:51:59+00:00"
+            "time": "2018-08-28T18:23:01+00:00"
         },
         {
             "name": "delight-im/http",

src/Administration.php

@@ -12,17 +12,16 @@ use Delight\Db\PdoDatabase;
 use Delight\Db\PdoDsn;
 use Delight\Db\Throwable\Error;
 
-require_once __DIR__ . '/Exceptions.php';
-
 /** Component that can be used for administrative tasks by privileged and authorized users */
 final class Administration extends UserManager {
 
 	/**
 	 * @param PdoDatabase|PdoDsn|\PDO $databaseConnection the database connection to operate on
 	 * @param string|null $dbTablePrefix (optional) the prefix for the names of all database tables used by this component
+	 * @param string|null $dbSchema (optional) the schema name for all database tables used by this component
 	 */
-	public function __construct($databaseConnection, $dbTablePrefix = null) {
-		parent::__construct($databaseConnection, $dbTablePrefix);
+	public function __construct($databaseConnection, $dbTablePrefix = null, $dbSchema = null) {
+		parent::__construct($databaseConnection, $dbTablePrefix, $dbSchema);
 	}
 
 	/**
@@ -277,7 +276,7 @@ final class Administration extends UserManager {
 		$userId = (int) $userId;
 
 		$rolesBitmask = $this->db->selectValue(
-			'SELECT roles_mask FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
+			'SELECT roles_mask FROM ' . $this->makeTableName('users') . ' WHERE id = ?',
 			[ $userId ]
 		);
 
@@ -303,7 +302,7 @@ final class Administration extends UserManager {
 		$userId = (int) $userId;
 
 		$rolesBitmask = $this->db->selectValue(
-			'SELECT roles_mask FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
+			'SELECT roles_mask FROM ' . $this->makeTableName('users') . ' WHERE id = ?',
 			[ $userId ]
 		);
 
@@ -430,7 +429,7 @@ final class Administration extends UserManager {
 	private function deleteUsersByColumnValue($columnName, $columnValue) {
 		try {
 			return $this->db->delete(
-				$this->dbTablePrefix . 'users',
+				$this->makeTableNameComponents('users'),
 				[
 					$columnName => $columnValue
 				]
@@ -457,7 +456,7 @@ final class Administration extends UserManager {
 	private function modifyRolesForUserByColumnValue($columnName, $columnValue, callable $modification) {
 		try {
 			$userData = $this->db->selectRow(
-				'SELECT id, roles_mask FROM ' . $this->dbTablePrefix . 'users WHERE ' . $columnName . ' = ?',
+				'SELECT id, roles_mask FROM ' . $this->makeTableName('users') . ' WHERE ' . $columnName . ' = ?',
 				[ $columnValue ]
 			);
 		}
@@ -473,7 +472,7 @@ final class Administration extends UserManager {
 
 		try {
 			$this->db->exec(
-				'UPDATE ' . $this->dbTablePrefix . 'users SET roles_mask = ? WHERE id = ?',
+				'UPDATE ' . $this->makeTableName('users') . ' SET roles_mask = ? WHERE id = ?',
 				[
 					$newRolesBitmask,
 					(int) $userData['id']
@@ -549,7 +548,7 @@ final class Administration extends UserManager {
 	private function logInAsUserByColumnValue($columnName, $columnValue) {
 		try {
 			$users = $this->db->select(
-				'SELECT verified, id, email, username, status, roles_mask FROM ' . $this->dbTablePrefix . 'users WHERE ' . $columnName . ' = ? LIMIT 2 OFFSET 0',
+				'SELECT verified, id, email, username, status, roles_mask FROM ' . $this->makeTableName('users') . ' WHERE ' . $columnName . ' = ? LIMIT 2 OFFSET 0',
 				[ $columnValue ]
 			);
 		}

src/AmbiguousUsernameException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class AmbiguousUsernameException extends AuthException {}

src/AttemptCancelledException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class AttemptCancelledException extends AuthException {}

src/Auth.php

@@ -16,8 +16,6 @@ use Delight\Db\PdoDsn;
 use Delight\Db\Throwable\Error;
 use Delight\Db\Throwable\IntegrityConstraintViolationException;
 
-require_once __DIR__ . '/Exceptions.php';
-
 /** Component that provides all features and utilities for secure authentication of individual users */
 final class Auth extends UserManager {
 
@@ -35,13 +33,14 @@ final class Auth extends UserManager {
 
 	/**
 	 * @param PdoDatabase|PdoDsn|\PDO $databaseConnection the database connection to operate on
-	 * @param string $ipAddress the IP address that should be used instead of the default setting (if any), e.g. when behind a proxy
+	 * @param string|null $ipAddress (optional) the IP address that should be used instead of the default setting (if any), e.g. when behind a proxy
 	 * @param string|null $dbTablePrefix (optional) the prefix for the names of all database tables used by this component
 	 * @param bool|null $throttling (optional) whether throttling should be enabled (e.g. in production) or disabled (e.g. during development)
 	 * @param int|null $sessionResyncInterval (optional) the interval in seconds after which to resynchronize the session data with its authoritative source in the database
+	 * @param string|null $dbSchema (optional) the schema name for all database tables used by this component
 	 */
-	public function __construct($databaseConnection, $ipAddress = null, $dbTablePrefix = null, $throttling = null, $sessionResyncInterval = null) {
-		parent::__construct($databaseConnection, $dbTablePrefix);
+	public function __construct($databaseConnection, $ipAddress = null, $dbTablePrefix = null, $throttling = null, $sessionResyncInterval = null, $dbSchema = null) {
+		parent::__construct($databaseConnection, $dbTablePrefix, $dbSchema);
 
 		$this->ipAddress = !empty($ipAddress) ? $ipAddress : (isset($_SERVER['REMOTE_ADDR']) ? $_SERVER['REMOTE_ADDR'] : null);
 		$this->throttling = isset($throttling) ? (bool) $throttling : true;
@@ -114,7 +113,7 @@ final class Auth extends UserManager {
 				if (!empty($parts[0]) && !empty($parts[1])) {
 					try {
 						$rememberData = $this->db->selectRow(
-							'SELECT a.user, a.token, a.expires, b.email, b.username, b.status, b.roles_mask, b.force_logout FROM ' . $this->dbTablePrefix . 'users_remembered AS a JOIN ' . $this->dbTablePrefix . 'users AS b ON a.user = b.id WHERE a.selector = ?',
+							'SELECT a.user, a.token, a.expires, b.email, b.username, b.status, b.roles_mask, b.force_logout FROM ' . $this->makeTableName('users_remembered') . ' AS a JOIN ' . $this->makeTableName('users') . ' AS b ON a.user = b.id WHERE a.selector = ?',
 							[ $parts[0] ]
 						);
 					}
@@ -156,7 +155,7 @@ final class Auth extends UserManager {
 				// fetch the authoritative data from the database again
 				try {
 					$authoritativeData = $this->db->selectRow(
-						'SELECT email, username, status, roles_mask, force_logout FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
+						'SELECT email, username, status, roles_mask, force_logout FROM ' . $this->makeTableName('users') . ' WHERE id = ?',
 						[ $this->getUserId() ]
 					);
 				}
@@ -353,7 +352,7 @@ final class Auth extends UserManager {
 
 			try {
 				$expectedHash = $this->db->selectValue(
-					'SELECT password FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
+					'SELECT password FROM ' . $this->makeTableName('users') . ' WHERE id = ?',
 					[ $this->getUserId() ]
 				);
 			}
@@ -496,7 +495,7 @@ final class Auth extends UserManager {
 
 		try {
 			$this->db->insert(
-				$this->dbTablePrefix . 'users_remembered',
+				$this->makeTableNameComponents('users_remembered'),
 				[
 					'user' => $userId,
 					'selector' => $selector,
@@ -566,7 +565,7 @@ final class Auth extends UserManager {
 		// update the timestamp of the user's last login
 		try {
 			$this->db->update(
-				$this->dbTablePrefix . 'users',
+				$this->makeTableNameComponents('users'),
 				[ 'last_login' => \time() ],
 				[ 'id' => $userId ]
 			);
@@ -620,7 +619,7 @@ final class Auth extends UserManager {
 
 		try {
 			$confirmationData = $this->db->selectRow(
-				'SELECT a.id, a.user_id, a.email AS new_email, a.token, a.expires, b.email AS old_email FROM ' . $this->dbTablePrefix . 'users_confirmations AS a JOIN ' . $this->dbTablePrefix . 'users AS b ON b.id = a.user_id WHERE a.selector = ?',
+				'SELECT a.id, a.user_id, a.email AS new_email, a.token, a.expires, b.email AS old_email FROM ' . $this->makeTableName('users_confirmations') . ' AS a JOIN ' . $this->makeTableName('users') . ' AS b ON b.id = a.user_id WHERE a.selector = ?',
 				[ $selector ]
 			);
 		}
@@ -634,7 +633,7 @@ final class Auth extends UserManager {
 					// invalidate any potential outstanding password reset requests
 					try {
 						$this->db->delete(
-							$this->dbTablePrefix . 'users_resets',
+							$this->makeTableNameComponents('users_resets'),
 							[ 'user' => $confirmationData['user_id'] ]
 						);
 					}
@@ -645,7 +644,7 @@ final class Auth extends UserManager {
 					// mark the email address as verified (and possibly update it to the new address given)
 					try {
 						$this->db->update(
-							$this->dbTablePrefix . 'users',
+							$this->makeTableNameComponents('users'),
 							[
 								'email' => $confirmationData['new_email'],
 								'verified' => 1
@@ -672,7 +671,7 @@ final class Auth extends UserManager {
 					// consume the token just being used for confirmation
 					try {
 						$this->db->delete(
-							$this->dbTablePrefix . 'users_confirmations',
+							$this->makeTableNameComponents('users_confirmations'),
 							[ 'id' => $confirmationData['id'] ]
 						);
 					}
@@ -817,7 +816,7 @@ final class Auth extends UserManager {
 
 			try {
 				$existingUsersWithNewEmail = $this->db->selectValue(
-					'SELECT COUNT(*) FROM ' . $this->dbTablePrefix . 'users WHERE email = ?',
+					'SELECT COUNT(*) FROM ' . $this->makeTableName('users') . ' WHERE email = ?',
 					[ $newEmail ]
 				);
 			}
@@ -831,7 +830,7 @@ final class Auth extends UserManager {
 
 			try {
 				$verified = $this->db->selectValue(
-					'SELECT verified FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
+					'SELECT verified FROM ' . $this->makeTableName('users') . ' WHERE id = ?',
 					[ $this->getUserId() ]
 				);
 			}
@@ -919,7 +918,7 @@ final class Auth extends UserManager {
 	private function resendConfirmationForColumnValue($columnName, $columnValue, callable $callback) {
 		try {
 			$latestAttempt = $this->db->selectRow(
-				'SELECT user_id, email FROM ' . $this->dbTablePrefix . 'users_confirmations WHERE ' . $columnName . ' = ? ORDER BY id DESC LIMIT 1 OFFSET 0',
+				'SELECT user_id, email FROM ' . $this->makeTableName('users_confirmations') . ' WHERE ' . $columnName . ' = ? ORDER BY id DESC LIMIT 1 OFFSET 0',
 				[ $columnValue ]
 			);
 		}
@@ -961,6 +960,11 @@ final class Auth extends UserManager {
 	 * @throws ResetDisabledException if the user has explicitly disabled password resets for their account
 	 * @throws TooManyRequestsException if the number of allowed attempts/requests has been exceeded
 	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 *
+	 * @see canResetPasswordOrThrow
+	 * @see canResetPassword
+	 * @see resetPassword
+	 * @see resetPasswordAndSignIn
 	 */
 	public function forgotPassword($email, callable $callback, $requestExpiresAfter = null, $maxOpenRequests = null) {
 		$email = self::validateEmailAddress($email);
@@ -998,7 +1002,7 @@ final class Auth extends UserManager {
 			throw new ResetDisabledException();
 		}
 
-		$openRequests = (int) $this->getOpenPasswordResetRequests($userData['id']);
+		$openRequests = $this->throttling ? (int) $this->getOpenPasswordResetRequests($userData['id']) : 0;
 
 		if ($openRequests < $maxOpenRequests) {
 			$this->throttle([ 'requestPasswordReset', $this->getIpAddress() ], 4, (60 * 60 * 24 * 7), 2);
@@ -1132,7 +1136,7 @@ final class Auth extends UserManager {
 		try {
 			$projection = \implode(', ', $requestedColumns);
 			$userData = $this->db->selectRow(
-				'SELECT ' . $projection . ' FROM ' . $this->dbTablePrefix . 'users WHERE email = ?',
+				'SELECT ' . $projection . ' FROM ' . $this->makeTableName('users') . ' WHERE email = ?',
 				[ $email ]
 			);
 		}
@@ -1158,7 +1162,7 @@ final class Auth extends UserManager {
 	private function getOpenPasswordResetRequests($userId) {
 		try {
 			$requests = $this->db->selectValue(
-				'SELECT COUNT(*) FROM ' . $this->dbTablePrefix . 'users_resets WHERE user = ? AND expires > ?',
+				'SELECT COUNT(*) FROM ' . $this->makeTableName('users_resets') . ' WHERE user = ? AND expires > ?',
 				[
 					$userId,
 					\time()
@@ -1201,7 +1205,7 @@ final class Auth extends UserManager {
 
 		try {
 			$this->db->insert(
-				$this->dbTablePrefix . 'users_resets',
+				$this->makeTableNameComponents('users_resets'),
 				[
 					'user' => $userId,
 					'selector' => $selector,
@@ -1225,17 +1229,23 @@ final class Auth extends UserManager {
 	/**
 	 * Resets the password for a particular account by supplying the correct selector/token pair
 	 *
-	 * The selector/token pair must have been generated previously by calling `Auth#forgotPassword(...)`
+	 * The selector/token pair must have been generated previously by calling {@see forgotPassword}
 	 *
 	 * @param string $selector the selector from the selector/token pair
 	 * @param string $token the token from the selector/token pair
 	 * @param string $newPassword the new password to set for the account
+	 * @return string[] an array with the user's ID at index `id` and the user's email address at index `email`
 	 * @throws InvalidSelectorTokenPairException if either the selector or the token was not correct
 	 * @throws TokenExpiredException if the token has already expired
 	 * @throws ResetDisabledException if the user has explicitly disabled password resets for their account
 	 * @throws InvalidPasswordException if the new password was invalid
 	 * @throws TooManyRequestsException if the number of allowed attempts/requests has been exceeded
 	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 *
+	 * @see forgotPassword
+	 * @see canResetPasswordOrThrow
+	 * @see canResetPassword
+	 * @see resetPasswordAndSignIn
 	 */
 	public function resetPassword($selector, $token, $newPassword) {
 		$this->throttle([ 'resetPassword', $this->getIpAddress() ], 5, (60 * 60), 10);
@@ -1244,7 +1254,7 @@ final class Auth extends UserManager {
 
 		try {
 			$resetData = $this->db->selectRow(
-				'SELECT a.id, a.user, a.token, a.expires, b.resettable FROM ' . $this->dbTablePrefix . 'users_resets AS a JOIN ' . $this->dbTablePrefix . 'users AS b ON b.id = a.user WHERE a.selector = ?',
+				'SELECT a.id, a.user, a.token, a.expires, b.email, b.resettable FROM ' . $this->makeTableName('users_resets') . ' AS a JOIN ' . $this->makeTableName('users') . ' AS b ON b.id = a.user WHERE a.selector = ?',
 				[ $selector ]
 			);
 		}
@@ -1262,13 +1272,18 @@ final class Auth extends UserManager {
 
 						try {
 							$this->db->delete(
-								$this->dbTablePrefix . 'users_resets',
+								$this->makeTableNameComponents('users_resets'),
 								[ 'id' => $resetData['id'] ]
 							);
 						}
 						catch (Error $e) {
 							throw new DatabaseError($e->getMessage());
 						}
+
+						return [
+							'id' => $resetData['user'],
+							'email' => $resetData['email']
+						];
 					}
 					else {
 						throw new TokenExpiredException();
@@ -1287,12 +1302,57 @@ final class Auth extends UserManager {
 		}
 	}
 
+	/**
+	 * Resets the password for a particular account by supplying the correct selector/token pair
+	 *
+	 * The selector/token pair must have been generated previously by calling {@see forgotPassword}
+	 *
+	 * The user will be automatically signed in if this operation is successful
+	 *
+	 * @param string $selector the selector from the selector/token pair
+	 * @param string $token the token from the selector/token pair
+	 * @param string $newPassword the new password to set for the account
+	 * @param int|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
+	 * @return string[] an array with the user's ID at index `id` and the user's email address at index `email`
+	 * @throws InvalidSelectorTokenPairException if either the selector or the token was not correct
+	 * @throws TokenExpiredException if the token has already expired
+	 * @throws ResetDisabledException if the user has explicitly disabled password resets for their account
+	 * @throws InvalidPasswordException if the new password was invalid
+	 * @throws TooManyRequestsException if the number of allowed attempts/requests has been exceeded
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 *
+	 * @see forgotPassword
+	 * @see canResetPasswordOrThrow
+	 * @see canResetPassword
+	 * @see resetPassword
+	 */
+	public function resetPasswordAndSignIn($selector, $token, $newPassword, $rememberDuration = null) {
+		$idAndEmail = $this->resetPassword($selector, $token, $newPassword);
+
+		if (!$this->isLoggedIn()) {
+			$idAndEmail['email'] = self::validateEmailAddress($idAndEmail['email']);
+
+			$userData = $this->getUserDataByEmailAddress(
+				$idAndEmail['email'],
+				[ 'username', 'status', 'roles_mask', 'force_logout' ]
+			);
+
+			$this->onLoginSuccessful($idAndEmail['id'], $idAndEmail['email'], $userData['username'], $userData['status'], $userData['roles_mask'], $userData['force_logout'], true);
+
+			if ($rememberDuration !== null) {
+				$this->createRememberDirective($idAndEmail['id'], $rememberDuration);
+			}
+		}
+
+		return $idAndEmail;
+	}
+
 	/**
 	 * Check if the supplied selector/token pair can be used to reset a password
 	 *
 	 * The password can be reset using the supplied information if this method does *not* throw any exception
 	 *
-	 * The selector/token pair must have been generated previously by calling `Auth#forgotPassword(...)`
+	 * The selector/token pair must have been generated previously by calling {@see forgotPassword}
 	 *
 	 * @param string $selector the selector from the selector/token pair
 	 * @param string $token the token from the selector/token pair
@@ -1301,6 +1361,11 @@ final class Auth extends UserManager {
 	 * @throws ResetDisabledException if the user has explicitly disabled password resets for their account
 	 * @throws TooManyRequestsException if the number of allowed attempts/requests has been exceeded
 	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 *
+	 * @see forgotPassword
+	 * @see canResetPassword
+	 * @see resetPassword
+	 * @see resetPasswordAndSignIn
 	 */
 	public function canResetPasswordOrThrow($selector, $token) {
 		try {
@@ -1324,12 +1389,17 @@ final class Auth extends UserManager {
 	/**
 	 * Check if the supplied selector/token pair can be used to reset a password
 	 *
-	 * The selector/token pair must have been generated previously by calling `Auth#forgotPassword(...)`
+	 * The selector/token pair must have been generated previously by calling {@see forgotPassword}
 	 *
 	 * @param string $selector the selector from the selector/token pair
 	 * @param string $token the token from the selector/token pair
 	 * @return bool whether the password can be reset using the supplied information
 	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 *
+	 * @see forgotPassword
+	 * @see canResetPasswordOrThrow
+	 * @see resetPassword
+	 * @see resetPasswordAndSignIn
 	 */
 	public function canResetPassword($selector, $token) {
 		try {
@@ -1355,7 +1425,7 @@ final class Auth extends UserManager {
 		if ($this->isLoggedIn()) {
 			try {
 				$this->db->update(
-					$this->dbTablePrefix . 'users',
+					$this->makeTableNameComponents('users'),
 					[
 						'resettable' => $enabled ? 1 : 0
 					],
@@ -1384,7 +1454,7 @@ final class Auth extends UserManager {
 		if ($this->isLoggedIn()) {
 			try {
 				$enabled = $this->db->selectValue(
-					'SELECT resettable FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
+					'SELECT resettable FROM ' . $this->makeTableName('users') . ' WHERE id = ?',
 					[ $this->getUserId() ]
 				);
 
@@ -1432,7 +1502,7 @@ final class Auth extends UserManager {
 	}
 
 	/**
-	 * Shorthand/alias for `getUserId()`
+	 * Shorthand/alias for {@see getUserId}
 	 *
 	 * @return int
 	 */
@@ -1691,7 +1761,7 @@ final class Auth extends UserManager {
 
 		try {
 			$bucket = $this->db->selectRow(
-				'SELECT tokens, replenished_at FROM ' . $this->dbTablePrefix . 'users_throttling WHERE bucket = ?',
+				'SELECT tokens, replenished_at FROM ' . $this->makeTableName('users_throttling') . ' WHERE bucket = ?',
 				[ $key ]
 			);
 		}
@@ -1728,7 +1798,7 @@ final class Auth extends UserManager {
 			// merge the updated bucket into the database
 			try {
 				$affected = $this->db->update(
-					$this->dbTablePrefix . 'users_throttling',
+					$this->makeTableNameComponents('users_throttling'),
 					$bucket,
 					[ 'bucket' => $key ]
 				);
@@ -1742,7 +1812,7 @@ final class Auth extends UserManager {
 
 				try {
 					$this->db->insert(
-						$this->dbTablePrefix . 'users_throttling',
+						$this->makeTableNameComponents('users_throttling'),
 						$bucket
 					);
 				}
@@ -1772,7 +1842,7 @@ final class Auth extends UserManager {
 	 * @return Administration
 	 */
 	public function admin() {
-		return new Administration($this->db, $this->dbTablePrefix);
+		return new Administration($this->db, $this->dbTablePrefix, $this->dbSchema);
 	}
 
 	/**
@@ -1868,7 +1938,7 @@ final class Auth extends UserManager {
 			if (isset($existingSelector)) {
 				// fetch the expiry date for the given selector
 				$existingExpiry = $this->db->selectValue(
-					'SELECT expires FROM ' . $this->dbTablePrefix . 'users_remembered WHERE selector = ? AND user = ?',
+					'SELECT expires FROM ' . $this->makeTableName('users_remembered') . ' WHERE selector = ? AND user = ?',
 					[
 						$existingSelector,
 						$this->getUserId()

src/AuthError.php

@@ -0,0 +1,12 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+/** Base class for all (unchecked) errors */
+class AuthError extends \Exception {}

src/AuthException.php

@@ -0,0 +1,12 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+/** Base class for all (checked) exceptions */
+class AuthException extends \Exception {}

src/ConfirmationRequestNotFound.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class ConfirmationRequestNotFound extends AuthException {}

src/DatabaseError.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class DatabaseError extends AuthError {}

src/DuplicateUsernameException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class DuplicateUsernameException extends AuthException {}

src/EmailNotVerifiedException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class EmailNotVerifiedException extends AuthException {}

src/EmailOrUsernameRequiredError.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class EmailOrUsernameRequiredError extends AuthError {}

src/Exceptions.php

@@ -1,53 +0,0 @@
-<?php
-
-/*
- * PHP-Auth (https://github.com/delight-im/PHP-Auth)
- * Copyright (c) delight.im (https://www.delight.im/)
- * Licensed under the MIT License (https://opensource.org/licenses/MIT)
- */
-
-namespace Delight\Auth;
-
-class AuthException extends \Exception {}
-
-class UnknownIdException extends AuthException {}
-
-class InvalidEmailException extends AuthException {}
-
-class UnknownUsernameException extends AuthException {}
-
-class InvalidPasswordException extends AuthException {}
-
-class EmailNotVerifiedException extends AuthException {}
-
-class UserAlreadyExistsException extends AuthException {}
-
-class NotLoggedInException extends AuthException {}
-
-class InvalidSelectorTokenPairException extends AuthException {}
-
-class TokenExpiredException extends AuthException {}
-
-class TooManyRequestsException extends AuthException {}
-
-class DuplicateUsernameException extends AuthException {}
-
-class AmbiguousUsernameException extends AuthException {}
-
-class AttemptCancelledException extends AuthException {}
-
-class ResetDisabledException extends AuthException {}
-
-class ConfirmationRequestNotFound extends AuthException {}
-
-class AuthError extends \Exception {}
-
-class DatabaseError extends AuthError {}
-
-class DatabaseDriverError extends DatabaseError {}
-
-class MissingCallbackError extends AuthError {}
-
-class HeadersAlreadySentError extends AuthError {}
-
-class EmailOrUsernameRequiredError extends AuthError {}

src/HeadersAlreadySentError.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class HeadersAlreadySentError extends AuthError {}

src/InvalidEmailException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class InvalidEmailException extends AuthException {}

src/InvalidPasswordException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class InvalidPasswordException extends AuthException {}

src/InvalidSelectorTokenPairException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class InvalidSelectorTokenPairException extends AuthException {}

src/MissingCallbackError.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class MissingCallbackError extends AuthError {}

src/NotLoggedInException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class NotLoggedInException extends AuthException {}

src/ResetDisabledException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class ResetDisabledException extends AuthException {}

src/TokenExpiredException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class TokenExpiredException extends AuthException {}

src/TooManyRequestsException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class TooManyRequestsException extends AuthException {}

src/UnknownIdException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class UnknownIdException extends AuthException {}

src/UnknownUsernameException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class UnknownUsernameException extends AuthException {}

src/UserAlreadyExistsException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class UserAlreadyExistsException extends AuthException {}

src/UserManager.php

@@ -15,8 +15,6 @@ use Delight\Db\PdoDsn;
 use Delight\Db\Throwable\Error;
 use Delight\Db\Throwable\IntegrityConstraintViolationException;
 
-require_once __DIR__ . '/Exceptions.php';
-
 /**
  * Abstract base class for components implementing user management
  *
@@ -45,6 +43,8 @@ abstract class UserManager {
 
 	/** @var PdoDatabase the database connection to operate on */
 	protected $db;
+	/** @var string|null the schema name for all database tables used by this component */
+	protected $dbSchema;
 	/** @var string the prefix for the names of all database tables used by this component */
 	protected $dbTablePrefix;
 
@@ -70,8 +70,9 @@ abstract class UserManager {
 	/**
 	 * @param PdoDatabase|PdoDsn|\PDO $databaseConnection the database connection to operate on
 	 * @param string|null $dbTablePrefix (optional) the prefix for the names of all database tables used by this component
+	 * @param string|null $dbSchema (optional) the schema name for all database tables used by this component
 	 */
-	protected function __construct($databaseConnection, $dbTablePrefix = null) {
+	protected function __construct($databaseConnection, $dbTablePrefix = null, $dbSchema = null) {
 		if ($databaseConnection instanceof PdoDatabase) {
 			$this->db = $databaseConnection;
 		}
@@ -87,6 +88,7 @@ abstract class UserManager {
 			throw new \InvalidArgumentException('The database connection must be an instance of either `PdoDatabase`, `PdoDsn` or `PDO`');
 		}
 
+		$this->dbSchema = $dbSchema !== null ? (string) $dbSchema : null;
 		$this->dbTablePrefix = (string) $dbTablePrefix;
 	}
 
@@ -140,7 +142,7 @@ abstract class UserManager {
 			if ($username !== null) {
 				// count the number of users who do already have that specified username
 				$occurrencesOfUsername = $this->db->selectValue(
-					'SELECT COUNT(*) FROM ' . $this->dbTablePrefix . 'users WHERE username = ?',
+					'SELECT COUNT(*) FROM ' . $this->makeTableName('users') . ' WHERE username = ?',
 					[ $username ]
 				);
 
@@ -157,7 +159,7 @@ abstract class UserManager {
 
 		try {
 			$this->db->insert(
-				$this->dbTablePrefix . 'users',
+				$this->makeTableNameComponents('users'),
 				[
 					'email' => $email,
 					'password' => $password,
@@ -197,7 +199,7 @@ abstract class UserManager {
 
 		try {
 			$affected = $this->db->update(
-				$this->dbTablePrefix . 'users',
+				$this->makeTableNameComponents('users'),
 				[ 'password' => $newPassword ],
 				[ 'id' => $userId ]
 			);
@@ -258,7 +260,7 @@ abstract class UserManager {
 			$projection = \implode(', ', $requestedColumns);
 
 			$users = $this->db->select(
-				'SELECT ' . $projection . ' FROM ' . $this->dbTablePrefix . 'users WHERE username = ? LIMIT 2 OFFSET 0',
+				'SELECT ' . $projection . ' FROM ' . $this->makeTableName('users') . ' WHERE username = ? LIMIT 2 OFFSET 0',
 				[ $username ]
 			);
 		}
@@ -345,7 +347,7 @@ abstract class UserManager {
 
 		try {
 			$this->db->insert(
-				$this->dbTablePrefix . 'users_confirmations',
+				$this->makeTableNameComponents('users_confirmations'),
 				[
 					'user_id' => (int) $userId,
 					'email' => $email,
@@ -385,7 +387,7 @@ abstract class UserManager {
 
 		try {
 			$this->db->delete(
-				$this->dbTablePrefix . 'users_remembered',
+				$this->makeTableNameComponents('users_remembered'),
 				$whereMappings
 			);
 		}
@@ -403,9 +405,50 @@ abstract class UserManager {
 	protected function forceLogoutForUserById($userId) {
 		$this->deleteRememberDirectiveForUserById($userId);
 		$this->db->exec(
-			'UPDATE ' . $this->dbTablePrefix . 'users SET force_logout = force_logout + 1 WHERE id = ?',
+			'UPDATE ' . $this->makeTableName('users') . ' SET force_logout = force_logout + 1 WHERE id = ?',
 			[ $userId ]
 		);
 	}
 
+	/**
+	 * Builds a (qualified) full table name from an optional qualifier, an optional prefix, and the table name itself
+	 *
+	 * The optional qualifier may be a database name or a schema name, for example
+	 *
+	 * @param string $name the name of the table
+	 * @return string[] the components of the (qualified) full name of the table
+	 */
+	protected function makeTableNameComponents($name) {
+		$components = [];
+
+		if (!empty($this->dbSchema)) {
+			$components[] = $this->dbSchema;
+		}
+
+		if (!empty($name)) {
+			if (!empty($this->dbTablePrefix)) {
+				$components[] = $this->dbTablePrefix . $name;
+			}
+			else {
+				$components[] = $name;
+			}
+		}
+
+		return $components;
+	}
+
+	/**
+	 * Builds a (qualified) full table name from an optional qualifier, an optional prefix, and the table name itself
+	 *
+	 * The optional qualifier may be a database name or a schema name, for example
+	 *
+	 * @param string $name the name of the table
+	 * @return string the (qualified) full name of the table
+	 */
+	protected function makeTableName($name) {
+		$components = $this->makeTableNameComponents($name);
+
+		return \implode('.', $components);
+	}
+
 }

tests/index.php

@@ -254,9 +254,21 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 			}
 			else if ($_POST['action'] === 'resetPassword') {
 				try {
-					$auth->resetPassword($_POST['selector'], $_POST['token'], $_POST['password']);
+					if (isset($_POST['login']) && $_POST['login'] > 0) {
+						if ($_POST['login'] == 2) {
+							// keep logged in for one year
+							$rememberDuration = (int) (60 * 60 * 24 * 365.25);
+						}
+						else {
+							// do not keep logged in after session ends
+							$rememberDuration = null;
+						}
 
-					return 'ok';
+						return $auth->resetPasswordAndSignIn($_POST['selector'], $_POST['token'], $_POST['password'], $rememberDuration);
+					}
+					else {
+						return $auth->resetPassword($_POST['selector'], $_POST['token'], $_POST['password']);
+					}
 				}
 				catch (\Delight\Auth\InvalidSelectorTokenPairException $e) {
 					return 'invalid token';
@@ -893,6 +905,11 @@ function showGuestUserForm() {
 	echo '<input type="text" name="selector" placeholder="Selector" /> ';
 	echo '<input type="text" name="token" placeholder="Token" /> ';
 	echo '<input type="text" name="password" placeholder="New password" /> ';
+	echo '<select name="login" size="1">';
+	echo '<option value="0">Sign in automatically? — No</option>';
+	echo '<option value="1">Sign in automatically? — Yes</option>';
+	echo '<option value="2">Sign in automatically? — Yes (and remember)</option>';
+	echo '</select> ';
 	echo '<button type="submit">Reset password</button>';
 	echo '</form>';