Move all exceptions and errors to separate files for autoloading

Explain where usernames may be used to address unconfirmed recipients
Explain how to impose restrictions on characters/length for usernames
2025-08-08 00:56:28 +02:00 · 2020-09-30 20:40:54 +02:00 · 2020-05-11 13:14:14 +02:00 · 2020-05-11 13:10:33 +02:00 · 2020-05-06 22:36:45 +02:00 · 2020-05-06 22:35:20 +02:00
33 changed files with 1105 additions and 364 deletions
--- a/Database/MySQL.sql
+++ b/Database/MySQL.sql
@@ -18,6 +18,7 @@ CREATE TABLE IF NOT EXISTS `users` (
  `roles_mask` int(10) unsigned NOT NULL DEFAULT '0',
  `registered` int(10) unsigned NOT NULL,
  `last_login` int(10) unsigned DEFAULT NULL,
+  `force_logout` mediumint(7) unsigned NOT NULL DEFAULT '0',
  PRIMARY KEY (`id`),
  UNIQUE KEY `email` (`email`)
 ) ENGINE=MyISAM DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
--- a/Database/PostgreSQL.sql
+++ b/Database/PostgreSQL.sql
@@ -14,7 +14,8 @@ CREATE TABLE IF NOT EXISTS "users" (
 	"resettable" SMALLINT NOT NULL DEFAULT '1' CHECK ("resettable" >= 0),
 	"roles_mask" INTEGER NOT NULL DEFAULT '0' CHECK ("roles_mask" >= 0),
 	"registered" INTEGER NOT NULL CHECK ("registered" >= 0),
-	"last_login" INTEGER DEFAULT NULL CHECK ("last_login" >= 0)
+	"last_login" INTEGER DEFAULT NULL CHECK ("last_login" >= 0),
+	"force_logout" INTEGER NOT NULL DEFAULT '0' CHECK ("force_logout" >= 0)
 );

 CREATE TABLE IF NOT EXISTS "users_confirmations" (
--- a/Database/SQLite.sql
+++ b/Database/SQLite.sql
@@ -15,6 +15,7 @@ CREATE TABLE "users" (
 	"roles_mask" INTEGER NOT NULL CHECK ("roles_mask" >= 0) DEFAULT "0",
 	"registered" INTEGER NOT NULL CHECK ("registered" >= 0),
 	"last_login" INTEGER CHECK ("last_login" >= 0) DEFAULT NULL,
+	"force_logout" INTEGER NOT NULL CHECK ("force_logout" >= 0) DEFAULT "0",
 	CONSTRAINT "email" UNIQUE ("email")
 );

--- a/Migration.md
+++ b/Migration.md
@@ -1,6 +1,7 @@
 # Migration

 * [General](#general)
+ * [From `v7.x.x` to `v8.x.x`](#from-v7xx-to-v8xx)
 * [From `v6.x.x` to `v7.x.x`](#from-v6xx-to-v7xx)
 * [From `v5.x.x` to `v6.x.x`](#from-v5xx-to-v6xx)
 * [From `v4.x.x` to `v5.x.x`](#from-v4xx-to-v5xx)
@@ -12,6 +13,35 @@

 Update your version of this library using Composer and its `composer update` or `composer require` commands [[?]](https://github.com/delight-im/Knowledge/blob/master/Composer%20(PHP).md#how-do-i-update-libraries-or-modules-within-my-application).

+## From `v7.x.x` to `v8.x.x`
+
+ * The database schema has changed.
+
+   * The MySQL database schema has changed. Use the statement below to update your database:
+
+     ```sql
+     ALTER TABLE users
+         ADD COLUMN `force_logout` mediumint(7) unsigned NOT NULL DEFAULT '0' AFTER `last_login`;
+     ```
+
+   * The PostgreSQL database schema has changed. Use the statement below to update your database:
+
+     ```sql
+     ALTER TABLE users
+         ADD COLUMN "force_logout" INTEGER NOT NULL DEFAULT '0' CHECK ("force_logout" >= 0);
+     ```
+
+   * The SQLite database schema has changed. Use the statement below to update your database:
+
+     ```sql
+     ALTER TABLE users
+         ADD COLUMN "force_logout" INTEGER NOT NULL CHECK ("force_logout" >= 0) DEFAULT "0";
+     ```
+
+ * The method `logOutAndDestroySession` has been removed from class `Auth`. Instead, call the two separate methods `logOut` and `destroySession` from class `Auth` one after another for the same effect.
+
+ * If you have been using the return values of the methods `confirmEmail` or `confirmEmailAndSignIn` from class `Auth`, these return values have changed. Instead of only returning the new email address (which has just been verified), both methods now return an array with the old email address (if any) at index zero and the new email address (which has just been verified) at index one.
+
 ## From `v6.x.x` to `v7.x.x`

 * The method `logOutButKeepSession` from class `Auth` is now simply called `logOut`. Therefore, the former method `logout` is now called `logOutAndDestroySession`.
--- a/README.md
+++ b/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)
@@ -82,6 +86,7 @@ Migrating from an earlier version of this project? See our [upgrade guide](Migra
   * [Taking roles away from users](#taking-roles-away-from-users)
   * [Checking roles](#checking-roles-1)
   * [Impersonating users (logging in as user)](#impersonating-users-logging-in-as-user)
+   * [Changing a user’s password](#changing-a-users-password)
 * [Cookies](#cookies)
   * [Renaming the library’s cookies](#renaming-the-librarys-cookies)
   * [Defining the domain scope for cookies](#defining-the-domain-scope-for-cookies)
@@ -113,7 +118,7 @@ Migrating from an earlier version of this project? See our [upgrade guide](Migra
 $auth = new \Delight\Auth\Auth($db);
 ```

-If you have an open `PDO` connection already, just re-use it.
+If you have an open `PDO` connection already, just re-use it. The database user (e.g. `my-username`) needs at least the privileges `SELECT`, `INSERT`, `UPDATE` and `DELETE` for the tables used by this library (or their parent database).

 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 second argument, which is named `$ipAddress`. The default is the usual remote IP address received by PHP.

@@ -123,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
@@ -159,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');
 }
 ```

@@ -191,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.
@@ -241,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.
@@ -276,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');
 }
 ```

@@ -299,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';
 }
 ```

@@ -314,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.
@@ -341,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');
 }
 ```

@@ -368,40 +399,46 @@ 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`.
+
 ### Re-sending confirmation requests

 If an earlier confirmation request could not be delivered to the user, or if the user missed that request, or if they just don’t want to wait any longer, you may re-send an earlier request like this:
@@ -409,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');
 }
 ```

@@ -427,45 +464,71 @@ 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
 $auth->logOut();
-// or
-$auth->logOutAndDestroySession();

-// user has been signed out
+// or
+
+try {
+    $auth->logOutEverywhereElse();
+}
+catch (\Delight\Auth\NotLoggedInException $e) {
+    die('Not logged in');
+}
+
+// or
+
+try {
+    $auth->logOutEverywhere();
+}
+catch (\Delight\Auth\NotLoggedInException $e) {
+    die('Not logged in');
+}
 ```

+Additionally, if you store custom information in the session as well, and if you want that information to be deleted, you can destroy the entire session by calling a second method:
+
+```php
+$auth->destroySession();
+```
+
+**Note:** Global logouts 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`.
+
 ### Accessing user information

 #### Login state

 ```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';
 }
 ```

@@ -492,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.
@@ -503,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';
 }
 ```

@@ -531,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';
 }
 ```

@@ -580,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');
 }
 ```

@@ -604,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';
 }
 ```

@@ -683,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';
 }
 ```

@@ -752,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');
 }
 ```

@@ -785,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
@@ -819,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');
 }
 ```

@@ -845,7 +908,7 @@ try {
    $auth->admin()->deleteUserById($_POST['id']);
 }
 catch (\Delight\Auth\UnknownIdException $e) {
-    // unknown ID
+    die('Unknown ID');
 }
 ```

@@ -856,7 +919,7 @@ try {
    $auth->admin()->deleteUserByEmail($_POST['email']);
 }
 catch (\Delight\Auth\InvalidEmailException $e) {
-    // unknown email address
+    die('Unknown email address');
 }
 ```

@@ -867,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
@@ -881,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
@@ -890,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
@@ -899,13 +972,15 @@ 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 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

 ```php
@@ -913,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
@@ -922,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
@@ -931,26 +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 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');
 }
 ```

@@ -967,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
@@ -979,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
@@ -991,13 +1068,42 @@ 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');
+}
+```
+
+#### Changing a user’s password
+
+```php
+try {
+    $auth->admin()->changePasswordForUserById($_POST['id'], $_POST['newPassword']);
+}
+catch (\Delight\Auth\UnknownIdException $e) {
+    die('Unknown ID');
+}
+catch (\Delight\Auth\InvalidPasswordException $e) {
+    die('Invalid password');
+}
+
+// or
+
+try {
+    $auth->admin()->changePasswordForUserByUsername($_POST['username'], $_POST['newPassword']);
+}
+catch (\Delight\Auth\UnknownUsernameException $e) {
+    die('Unknown username');
+}
+catch (\Delight\Auth\AmbiguousUsernameException $e) {
+    die('Ambiguous username');
+}
+catch (\Delight\Auth\InvalidPasswordException $e) {
+    die('Invalid password');
 }
 ```

--- a/composer.json
+++ b/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" ],
--- a/composer.lock
+++ b/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",
--- a/src/Administration.php
+++ b/src/Administration.php
@@ -9,21 +9,19 @@
 namespace Delight\Auth;

 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 {

 	/**
-	 * @internal
-	 *
-	 * @param PdoDatabase $databaseConnection the database connection to operate on
+	 * @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(PdoDatabase $databaseConnection, $dbTablePrefix = null) {
-		parent::__construct($databaseConnection, $dbTablePrefix);
+	public function __construct($databaseConnection, $dbTablePrefix = null, $dbSchema = null) {
+		parent::__construct($databaseConnection, $dbTablePrefix, $dbSchema);
 	}

 	/**
@@ -271,11 +269,14 @@ final class Administration extends UserManager {
 	 * @see Role
 	 */
 	public function doesUserHaveRole($userId, $role) {
+		if (empty($role) || !\is_numeric($role)) {
+			return false;
+		}
+
 		$userId = (int) $userId;
-		$role = (int) $role;

 		$rolesBitmask = $this->db->selectValue(
-			'SELECT roles_mask FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
+			'SELECT roles_mask FROM ' . $this->makeTableName('users') . ' WHERE id = ?',
 			[ $userId ]
 		);

@@ -283,6 +284,8 @@ final class Administration extends UserManager {
 			throw new UnknownIdException();
 		}

+		$role = (int) $role;
+
 		return ($rolesBitmask & $role) === $role;
 	}

@@ -299,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 ]
 		);

@@ -370,6 +373,49 @@ final class Administration extends UserManager {
 		}
 	}

+	/**
+	 * Changes the password for the user with the given ID
+	 *
+	 * @param int $userId the ID of the user whose password to change
+	 * @param string $newPassword the new password to set
+	 * @throws UnknownIdException if no user with the specified ID has been found
+	 * @throws InvalidPasswordException if the desired new password has been invalid
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function changePasswordForUserById($userId, $newPassword) {
+		$userId = (int) $userId;
+		$newPassword = self::validatePassword($newPassword);
+
+		$this->updatePasswordInternal(
+			$userId,
+			$newPassword
+		);
+
+		$this->forceLogoutForUserById($userId);
+	}
+
+	/**
+	 * Changes the password for the user with the given username
+	 *
+	 * @param string $username the username of the user whose password to change
+	 * @param string $newPassword the new password to set
+	 * @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 InvalidPasswordException if the desired new password has been invalid
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function changePasswordForUserByUsername($username, $newPassword) {
+		$userData = $this->getUserDataByUsername(
+			\trim($username),
+			[ 'id' ]
+		);
+
+		$this->changePasswordForUserById(
+			(int) $userData['id'],
+			$newPassword
+		);
+	}
+
 	/**
 	 * Deletes all existing users where the column with the specified name has the given value
 	 *
@@ -383,14 +429,14 @@ final class Administration extends UserManager {
 	private function deleteUsersByColumnValue($columnName, $columnValue) {
 		try {
 			return $this->db->delete(
-				$this->dbTablePrefix . 'users',
+				$this->makeTableNameComponents('users'),
 				[
 					$columnName => $columnValue
 				]
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 	}

@@ -410,12 +456,12 @@ 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 ]
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

 		if ($userData === null) {
@@ -426,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']
@@ -436,7 +482,7 @@ final class Administration extends UserManager {
 			return true;
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 	}

@@ -502,21 +548,21 @@ 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 ]
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

-		$numberOfMatchingUsers = \count($users);
+		$numberOfMatchingUsers = ($users !== null) ? \count($users) : 0;

 		if ($numberOfMatchingUsers === 1) {
 			$user = $users[0];

 			if ((int) $user['verified'] === 1) {
-				$this->onLoginSuccessful($user['id'], $user['email'], $user['username'], $user['status'], $user['roles_mask'], false);
+				$this->onLoginSuccessful($user['id'], $user['email'], $user['username'], $user['status'], $user['roles_mask'], \PHP_INT_MAX, false);
 			}
 			else {
 				throw new EmailNotVerifiedException();
--- a/src/AmbiguousUsernameException.php
+++ b/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 {}
--- a/src/AttemptCancelledException.php
+++ b/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 {}
--- a/src/Auth.php
+++ b/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,12 +113,12 @@ 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 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] ]
 						);
 					}
 					catch (Error $e) {
-						throw new DatabaseError();
+						throw new DatabaseError($e->getMessage());
 					}

 					if (!empty($rememberData)) {
@@ -128,7 +127,7 @@ final class Auth extends UserManager {
 								// the cookie and its contents have now been proven to be valid
 								$valid = true;

-								$this->onLoginSuccessful($rememberData['user'], $rememberData['email'], $rememberData['username'], $rememberData['status'], $rememberData['roles_mask'], true);
+								$this->onLoginSuccessful($rememberData['user'], $rememberData['email'], $rememberData['username'], $rememberData['status'], $rememberData['roles_mask'], $rememberData['force_logout'], true);
 							}
 						}
 					}
@@ -146,6 +145,7 @@ final class Auth extends UserManager {
 	private function resyncSessionIfNecessary() {
 		// if the user is signed in
 		if ($this->isLoggedIn()) {
+			// the following session field may not have been initialized for sessions that had already existed before the introduction of this feature
 			if (!isset($_SESSION[self::SESSION_FIELD_LAST_RESYNC])) {
 				$_SESSION[self::SESSION_FIELD_LAST_RESYNC] = 0;
 			}
@@ -155,30 +155,43 @@ final class Auth extends UserManager {
 				// fetch the authoritative data from the database again
 				try {
 					$authoritativeData = $this->db->selectRow(
-						'SELECT email, username, status, roles_mask FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
+						'SELECT email, username, status, roles_mask, force_logout FROM ' . $this->makeTableName('users') . ' WHERE id = ?',
 						[ $this->getUserId() ]
 					);
 				}
 				catch (Error $e) {
-					throw new DatabaseError();
+					throw new DatabaseError($e->getMessage());
 				}

 				// if the user's data has been found
 				if (!empty($authoritativeData)) {
-					// update the session data
-					$_SESSION[self::SESSION_FIELD_EMAIL] = $authoritativeData['email'];
-					$_SESSION[self::SESSION_FIELD_USERNAME] = $authoritativeData['username'];
-					$_SESSION[self::SESSION_FIELD_STATUS] = (int) $authoritativeData['status'];
-					$_SESSION[self::SESSION_FIELD_ROLES] = (int) $authoritativeData['roles_mask'];
+					// the following session field may not have been initialized for sessions that had already existed before the introduction of this feature
+					if (!isset($_SESSION[self::SESSION_FIELD_FORCE_LOGOUT])) {
+						$_SESSION[self::SESSION_FIELD_FORCE_LOGOUT] = 0;
+					}
+
+					// if the counter that keeps track of forced logouts has been incremented
+					if ($authoritativeData['force_logout'] > $_SESSION[self::SESSION_FIELD_FORCE_LOGOUT]) {
+						// the user must be signed out
+						$this->logOut();
+					}
+					// if the counter that keeps track of forced logouts has remained unchanged
+					else {
+						// the session data needs to be updated
+						$_SESSION[self::SESSION_FIELD_EMAIL] = $authoritativeData['email'];
+						$_SESSION[self::SESSION_FIELD_USERNAME] = $authoritativeData['username'];
+						$_SESSION[self::SESSION_FIELD_STATUS] = (int) $authoritativeData['status'];
+						$_SESSION[self::SESSION_FIELD_ROLES] = (int) $authoritativeData['roles_mask'];
+
+						// remember that we've just performed the required resynchronization
+						$_SESSION[self::SESSION_FIELD_LAST_RESYNC] = \time();
+					}
 				}
 				// if no data has been found for the user
 				else {
 					// their account may have been deleted so they should be signed out
 					$this->logOut();
 				}
-
-				// remember that we've just performed resynchronization
-				$_SESSION[self::SESSION_FIELD_LAST_RESYNC] = \time();
 			}
 		}
 	}
@@ -339,12 +352,12 @@ 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() ]
 				);
 			}
 			catch (Error $e) {
-				throw new DatabaseError();
+				throw new DatabaseError($e->getMessage());
 			}

 			if (!empty($expectedHash)) {
@@ -373,13 +386,16 @@ final class Auth extends UserManager {
 	public function logOut() {
 		// if the user has been signed in
 		if ($this->isLoggedIn()) {
-			// get the user's ID
-			$userId = $this->getUserId();
+			// retrieve any locally existing remember directive
+			$rememberDirectiveSelector = $this->getRememberDirectiveSelector();

-			// if a user ID was set
-			if (isset($userId)) {
-				// delete any existing remember directives
-				$this->deleteRememberDirective($userId);
+			// if such a remember directive exists
+			if (isset($rememberDirectiveSelector)) {
+				// delete the local remember directive
+				$this->deleteRememberDirectiveForUserById(
+					$this->getUserId(),
+					$rememberDirectiveSelector
+				);
 			}

 			// remove all session variables maintained by this library
@@ -391,9 +407,65 @@ final class Auth extends UserManager {
 			unset($_SESSION[self::SESSION_FIELD_ROLES]);
 			unset($_SESSION[self::SESSION_FIELD_REMEMBERED]);
 			unset($_SESSION[self::SESSION_FIELD_LAST_RESYNC]);
+			unset($_SESSION[self::SESSION_FIELD_FORCE_LOGOUT]);
 		}
 	}

+	/**
+	 * Logs the user out in all other sessions (except for the current one)
+	 *
+	 * @throws NotLoggedInException if the user is not currently signed in
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function logOutEverywhereElse() {
+		if (!$this->isLoggedIn()) {
+			throw new NotLoggedInException();
+		}
+
+		// determine the expiry date of any locally existing remember directive
+		$previousRememberDirectiveExpiry = $this->getRememberDirectiveExpiry();
+
+		// schedule a forced logout in all sessions
+		$this->forceLogoutForUserById($this->getUserId());
+
+		// the following session field may not have been initialized for sessions that had already existed before the introduction of this feature
+		if (!isset($_SESSION[self::SESSION_FIELD_FORCE_LOGOUT])) {
+			$_SESSION[self::SESSION_FIELD_FORCE_LOGOUT] = 0;
+		}
+
+		// ensure that we will simply skip or ignore the next forced logout (which we have just caused) in the current session
+		$_SESSION[self::SESSION_FIELD_FORCE_LOGOUT]++;
+
+		// re-generate the session ID to prevent session fixation attacks (requests a cookie to be written on the client)
+		Session::regenerate(true);
+
+		// if there had been an existing remember directive previously
+		if (isset($previousRememberDirectiveExpiry)) {
+			// restore the directive with the old expiry date but new credentials
+			$this->createRememberDirective(
+				$this->getUserId(),
+				$previousRememberDirectiveExpiry - \time()
+			);
+		}
+	}
+
+	/**
+	 * Logs the user out in all sessions
+	 *
+	 * @throws NotLoggedInException if the user is not currently signed in
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function logOutEverywhere() {
+		if (!$this->isLoggedIn()) {
+			throw new NotLoggedInException();
+		}
+
+		// schedule a forced logout in all sessions
+		$this->forceLogoutForUserById($this->getUserId());
+		// and immediately apply the logout locally
+		$this->logOut();
+	}
+
 	/**
 	 * Destroys all session data
 	 *
@@ -423,7 +495,7 @@ final class Auth extends UserManager {

 		try {
 			$this->db->insert(
-				$this->dbTablePrefix . 'users_remembered',
+				$this->makeTableNameComponents('users_remembered'),
 				[
 					'user' => $userId,
 					'selector' => $selector,
@@ -433,28 +505,14 @@ final class Auth extends UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

 		$this->setRememberCookie($selector, $token, $expires);
 	}

-	/**
-	 * Clears an existing directive that keeps the user logged in ("remember me")
-	 *
-	 * @param int $userId the user ID that shouldn't be kept signed in anymore
-	 * @throws AuthError if an internal problem occurred (do *not* catch)
-	 */
-	private function deleteRememberDirective($userId) {
-		try {
-			$this->db->delete(
-				$this->dbTablePrefix . 'users_remembered',
-				[ 'user' => $userId ]
-			);
-		}
-		catch (Error $e) {
-			throw new DatabaseError();
-		}
+	protected function deleteRememberDirectiveForUserById($userId, $selector = null) {
+		parent::deleteRememberDirectiveForUserById($userId, $selector);

 		$this->setRememberCookie(null, null, \time() - 3600);
 	}
@@ -503,30 +561,20 @@ final class Auth extends UserManager {
 		}
 	}

-	protected function onLoginSuccessful($userId, $email, $username, $status, $roles, $remembered) {
+	protected function onLoginSuccessful($userId, $email, $username, $status, $roles, $forceLogout, $remembered) {
 		// update the timestamp of the user's last login
 		try {
 			$this->db->update(
-				$this->dbTablePrefix . 'users',
+				$this->makeTableNameComponents('users'),
 				[ 'last_login' => \time() ],
 				[ 'id' => $userId ]
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

-		parent::onLoginSuccessful($userId, $email, $username, $status, $roles, $remembered);
-	}
-
-	/**
-	 * Logs the user out and destroys all session data
-	 *
-	 * @throws AuthError if an internal problem occurred (do *not* catch)
-	 */
-	public function logOutAndDestroySession() {
-		$this->logOut();
-		$this->destroySession();
+		parent::onLoginSuccessful($userId, $email, $username, $status, $roles, $forceLogout, $remembered);
 	}

 	/**
@@ -557,7 +605,7 @@ final class Auth extends UserManager {
 	 *
 	 * @param string $selector the selector from the selector/token pair
 	 * @param string $token the token from the selector/token pair
-	 * @return string the email address that has successfully been verified
+	 * @return string[] an array with the old email address (if any) at index zero and the new email address (which has just been verified) at index one
 	 * @throws InvalidSelectorTokenPairException if either the selector or the token was not correct
 	 * @throws TokenExpiredException if the token has already expired
 	 * @throws UserAlreadyExistsException if an attempt has been made to change the email address to a (now) occupied address
@@ -571,12 +619,12 @@ final class Auth extends UserManager {

 		try {
 			$confirmationData = $this->db->selectRow(
-				'SELECT id, user_id, email, token, expires FROM ' . $this->dbTablePrefix . 'users_confirmations WHERE 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 ]
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

 		if (!empty($confirmationData)) {
@@ -585,20 +633,20 @@ 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'] ]
 						);
 					}
 					catch (Error $e) {
-						throw new DatabaseError();
+						throw new DatabaseError($e->getMessage());
 					}

 					// 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['email'],
+								'email' => $confirmationData['new_email'],
 								'verified' => 1
 							],
 							[ 'id' => $confirmationData['user_id'] ]
@@ -608,7 +656,7 @@ final class Auth extends UserManager {
 						throw new UserAlreadyExistsException();
 					}
 					catch (Error $e) {
-						throw new DatabaseError();
+						throw new DatabaseError($e->getMessage());
 					}

 					// if the user is currently signed in
@@ -616,22 +664,31 @@ final class Auth extends UserManager {
 						// if the user has just confirmed an email address for their own account
 						if ($this->getUserId() === $confirmationData['user_id']) {
 							// immediately update the email address in the current session as well
-							$_SESSION[self::SESSION_FIELD_EMAIL] = $confirmationData['email'];
+							$_SESSION[self::SESSION_FIELD_EMAIL] = $confirmationData['new_email'];
 						}
 					}

 					// consume the token just being used for confirmation
 					try {
 						$this->db->delete(
-							$this->dbTablePrefix . 'users_confirmations',
+							$this->makeTableNameComponents('users_confirmations'),
 							[ 'id' => $confirmationData['id'] ]
 						);
 					}
 					catch (Error $e) {
-						throw new DatabaseError();
+						throw new DatabaseError($e->getMessage());
 					}

-					return $confirmationData['email'];
+					// if the email address has not been changed but simply been verified
+					if ($confirmationData['old_email'] === $confirmationData['new_email']) {
+						// the output should not contain any previous email address
+						$confirmationData['old_email'] = null;
+					}
+
+					return [
+						$confirmationData['old_email'],
+						$confirmationData['new_email']
+					];
 				}
 				else {
 					throw new TokenExpiredException();
@@ -656,7 +713,7 @@ final class Auth extends UserManager {
 	 * @param string $selector the selector from the selector/token pair
 	 * @param string $token the token from the selector/token pair
 	 * @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 the email address that has successfully been verified
+	 * @return string[] an array with the old email address (if any) at index zero and the new email address (which has just been verified) at index one
 	 * @throws InvalidSelectorTokenPairException if either the selector or the token was not correct
 	 * @throws TokenExpiredException if the token has already expired
 	 * @throws UserAlreadyExistsException if an attempt has been made to change the email address to a (now) occupied address
@@ -664,18 +721,18 @@ final class Auth extends UserManager {
 	 * @throws AuthError if an internal problem occurred (do *not* catch)
 	 */
 	public function confirmEmailAndSignIn($selector, $token, $rememberDuration = null) {
-		$verifiedEmail = $this->confirmEmail($selector, $token);
+		$emailBeforeAndAfter = $this->confirmEmail($selector, $token);

 		if (!$this->isLoggedIn()) {
-			if ($verifiedEmail !== null) {
-				$verifiedEmail = self::validateEmailAddress($verifiedEmail);
+			if ($emailBeforeAndAfter[1] !== null) {
+				$emailBeforeAndAfter[1] = self::validateEmailAddress($emailBeforeAndAfter[1]);

 				$userData = $this->getUserDataByEmailAddress(
-					$verifiedEmail,
-					[ 'id', 'email', 'username', 'status', 'roles_mask' ]
+					$emailBeforeAndAfter[1],
+					[ 'id', 'email', 'username', 'status', 'roles_mask', 'force_logout' ]
 				);

-				$this->onLoginSuccessful($userData['id'], $userData['email'], $userData['username'], $userData['status'], $userData['roles_mask'], true);
+				$this->onLoginSuccessful($userData['id'], $userData['email'], $userData['username'], $userData['status'], $userData['roles_mask'], $userData['force_logout'], true);

 				if ($rememberDuration !== null) {
 					$this->createRememberDirective($userData['id'], $rememberDuration);
@@ -683,7 +740,7 @@ final class Auth extends UserManager {
 			}
 		}

-		return $verifiedEmail;
+		return $emailBeforeAndAfter;
 	}

 	/**
@@ -716,37 +773,18 @@ final class Auth extends UserManager {
 	public function changePasswordWithoutOldPassword($newPassword) {
 		if ($this->isLoggedIn()) {
 			$newPassword = self::validatePassword($newPassword);
-			$userId = $this->getUserId();
-			$this->updatePassword($userId, $newPassword);
-			$this->deleteRememberDirective($userId);
+			$this->updatePasswordInternal($this->getUserId(), $newPassword);
+
+			try {
+				$this->logOutEverywhereElse();
+			}
+			catch (NotLoggedInException $ignored) {}
 		}
 		else {
 			throw new NotLoggedInException();
 		}
 	}

-	/**
-	 * Updates the given user's password by setting it to the new specified password
-	 *
-	 * @param int $userId the ID of the user whose password should be updated
-	 * @param string $newPassword the new password
-	 * @throws AuthError if an internal problem occurred (do *not* catch)
-	 */
-	private function updatePassword($userId, $newPassword) {
-		$newPassword = \password_hash($newPassword, \PASSWORD_DEFAULT);
-
-		try {
-			$this->db->update(
-				$this->dbTablePrefix . 'users',
-				[ 'password' => $newPassword ],
-				[ 'id' => $userId ]
-			);
-		}
-		catch (Error $e) {
-			throw new DatabaseError();
-		}
-	}
-
 	/**
 	 * Attempts to change the email address of the currently signed-in user (which requires confirmation)
 	 *
@@ -778,12 +816,12 @@ 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 ]
 				);
 			}
 			catch (Error $e) {
-				throw new DatabaseError();
+				throw new DatabaseError($e->getMessage());
 			}

 			if ((int) $existingUsersWithNewEmail !== 0) {
@@ -792,12 +830,12 @@ 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() ]
 				);
 			}
 			catch (Error $e) {
-				throw new DatabaseError();
+				throw new DatabaseError($e->getMessage());
 			}

 			// ensure that at least the current (old) email address has been verified before proceeding
@@ -880,12 +918,12 @@ 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 ]
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

 		if ($latestAttempt === null) {
@@ -922,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);
@@ -959,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);
@@ -993,7 +1036,7 @@ final class Auth extends UserManager {
 		$this->throttle([ 'enumerateUsers', $this->getIpAddress() ], 1, (60 * 60), 75);
 		$this->throttle([ 'attemptToLogin', $this->getIpAddress() ], 4, (60 * 60), 5, true);

-		$columnsToFetch = [ 'id', 'email', 'password', 'verified', 'username', 'status', 'roles_mask' ];
+		$columnsToFetch = [ 'id', 'email', 'password', 'verified', 'username', 'status', 'roles_mask', 'force_logout' ];

 		if ($email !== null) {
 			$email = self::validateEmailAddress($email);
@@ -1025,12 +1068,12 @@ final class Auth extends UserManager {
 			// 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);
+				$this->updatePasswordInternal($userData['id'], $password);
 			}

 			if ((int) $userData['verified'] === 1) {
 				if (!isset($onBeforeSuccess) || (\is_callable($onBeforeSuccess) && $onBeforeSuccess($userData['id']) === true)) {
-					$this->onLoginSuccessful($userData['id'], $userData['email'], $userData['username'], $userData['status'], $userData['roles_mask'], false);
+					$this->onLoginSuccessful($userData['id'], $userData['email'], $userData['username'], $userData['status'], $userData['roles_mask'], $userData['force_logout'], false);

 					// continue to support the old parameter format
 					if ($rememberDuration === true) {
@@ -1093,12 +1136,12 @@ 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 ]
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

 		if (!empty($userData)) {
@@ -1119,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()
@@ -1134,7 +1177,7 @@ final class Auth extends UserManager {
 			}
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 	}

@@ -1162,7 +1205,7 @@ final class Auth extends UserManager {

 		try {
 			$this->db->insert(
-				$this->dbTablePrefix . 'users_resets',
+				$this->makeTableNameComponents('users_resets'),
 				[
 					'user' => $userId,
 					'selector' => $selector,
@@ -1172,7 +1215,7 @@ final class Auth extends UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

 		if (\is_callable($callback)) {
@@ -1186,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);
@@ -1205,12 +1254,12 @@ 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 ]
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

 		if (!empty($resetData)) {
@@ -1218,22 +1267,23 @@ final class Auth extends UserManager {
 				if (\password_verify($token, $resetData['token'])) {
 					if ($resetData['expires'] >= \time()) {
 						$newPassword = self::validatePassword($newPassword);
-
-						// update the password in the database
-						$this->updatePassword($resetData['user'], $newPassword);
-
-						// delete any remaining remember directives
-						$this->deleteRememberDirective($resetData['user']);
+						$this->updatePasswordInternal($resetData['user'], $newPassword);
+						$this->forceLogoutForUserById($resetData['user']);

 						try {
 							$this->db->delete(
-								$this->dbTablePrefix . 'users_resets',
+								$this->makeTableNameComponents('users_resets'),
 								[ 'id' => $resetData['id'] ]
 							);
 						}
 						catch (Error $e) {
-							throw new DatabaseError();
+							throw new DatabaseError($e->getMessage());
 						}
+
+						return [
+							'id' => $resetData['user'],
+							'email' => $resetData['email']
+						];
 					}
 					else {
 						throw new TokenExpiredException();
@@ -1252,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
@@ -1266,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 {
@@ -1289,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 {
@@ -1320,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
 					],
@@ -1330,7 +1435,7 @@ final class Auth extends UserManager {
 				);
 			}
 			catch (Error $e) {
-				throw new DatabaseError();
+				throw new DatabaseError($e->getMessage());
 			}
 		}
 		else {
@@ -1349,14 +1454,14 @@ 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() ]
 				);

 				return (int) $enabled === 1;
 			}
 			catch (Error $e) {
-				throw new DatabaseError();
+				throw new DatabaseError($e->getMessage());
 			}
 		}
 		else {
@@ -1397,7 +1502,7 @@ final class Auth extends UserManager {
 	}

 	/**
-	 * Shorthand/alias for `getUserId()`
+	 * Shorthand/alias for {@see getUserId}
 	 *
 	 * @return int
 	 */
@@ -1528,9 +1633,13 @@ final class Auth extends UserManager {
 	 * @see Role
 	 */
 	public function hasRole($role) {
-		$role = (int) $role;
+		if (empty($role) || !\is_numeric($role)) {
+			return false;
+		}

 		if (isset($_SESSION) && isset($_SESSION[self::SESSION_FIELD_ROLES])) {
+			$role = (int) $role;
+
 			return (((int) $_SESSION[self::SESSION_FIELD_ROLES]) & $role) === $role;
 		}
 		else {
@@ -1652,12 +1761,12 @@ 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 ]
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

 		if ($bucket === null) {
@@ -1689,13 +1798,13 @@ 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 ]
 				);
 			}
 			catch (Error $e) {
-				throw new DatabaseError();
+				throw new DatabaseError($e->getMessage());
 			}

 			if ($affected === 0) {
@@ -1703,13 +1812,13 @@ final class Auth extends UserManager {

 				try {
 					$this->db->insert(
-						$this->dbTablePrefix . 'users_throttling',
+						$this->makeTableNameComponents('users_throttling'),
 						$bucket
 					);
 				}
 				catch (IntegrityConstraintViolationException $ignored) {}
 				catch (Error $e) {
-					throw new DatabaseError();
+					throw new DatabaseError($e->getMessage());
 				}
 			}
 		}
@@ -1733,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);
 	}

 	/**
@@ -1798,4 +1907,53 @@ final class Auth extends UserManager {
 		);
 	}

+	/**
+	 * Returns the selector of a potential locally existing remember directive
+	 *
+	 * @return string|null
+	 */
+	private function getRememberDirectiveSelector() {
+		if (isset($_COOKIE[$this->rememberCookieName])) {
+			$selectorAndToken = \explode(self::COOKIE_CONTENT_SEPARATOR, $_COOKIE[$this->rememberCookieName], 2);
+
+			return $selectorAndToken[0];
+		}
+		else {
+			return null;
+		}
+	}
+
+	/**
+	 * Returns the expiry date of a potential locally existing remember directive
+	 *
+	 * @return int|null
+	 */
+	private function getRememberDirectiveExpiry() {
+		// if the user is currently signed in
+		if ($this->isLoggedIn()) {
+			// determine the selector of any currently existing remember directive
+			$existingSelector = $this->getRememberDirectiveSelector();
+
+			// if there is currently a remember directive whose selector we have just retrieved
+			if (isset($existingSelector)) {
+				// fetch the expiry date for the given selector
+				$existingExpiry = $this->db->selectValue(
+					'SELECT expires FROM ' . $this->makeTableName('users_remembered') . ' WHERE selector = ? AND user = ?',
+					[
+						$existingSelector,
+						$this->getUserId()
+					]
+				);
+
+				// if an expiration date has been found
+				if (isset($existingExpiry)) {
+					// return the date
+					return (int) $existingExpiry;
+				}
+			}
+		}
+
+		return null;
+	}
+
 }
--- a/src/AuthError.php
+++ b/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 {}
--- a/src/AuthException.php
+++ b/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 {}
--- a/src/ConfirmationRequestNotFound.php
+++ b/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 {}
--- a/src/DatabaseError.php
+++ b/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 {}
--- a/src/DuplicateUsernameException.php
+++ b/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 {}
--- a/src/EmailNotVerifiedException.php
+++ b/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 {}
--- a/src/EmailOrUsernameRequiredError.php
+++ b/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 {}
--- a/src/Exceptions.php
+++ b/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 {}
--- a/src/HeadersAlreadySentError.php
+++ b/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 {}
--- a/src/InvalidEmailException.php
+++ b/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 {}
--- a/src/InvalidPasswordException.php
+++ b/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 {}
--- a/src/InvalidSelectorTokenPairException.php
+++ b/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 {}
--- a/src/MissingCallbackError.php
+++ b/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 {}
--- a/src/NotLoggedInException.php
+++ b/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 {}
--- a/src/ResetDisabledException.php
+++ b/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 {}
--- a/src/TokenExpiredException.php
+++ b/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 {}
--- a/src/TooManyRequestsException.php
+++ b/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 {}
--- a/src/UnknownIdException.php
+++ b/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 {}
--- a/src/UnknownUsernameException.php
+++ b/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 {}
--- a/src/UserAlreadyExistsException.php
+++ b/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 {}
--- a/src/UserManager.php
+++ b/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
 *
@@ -40,9 +38,13 @@ abstract class UserManager {
 	const SESSION_FIELD_REMEMBERED = 'auth_remembered';
 	/** @var string session field for the UNIX timestamp in seconds of the session data's last resynchronization with its authoritative source in the database */
 	const SESSION_FIELD_LAST_RESYNC = 'auth_last_resync';
+	/** @var string session field for the counter that keeps track of forced logouts that need to be performed in the current session */
+	const SESSION_FIELD_FORCE_LOGOUT = 'auth_force_logout';

 	/** @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;

@@ -68,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;
 		}
@@ -85,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;
 	}

@@ -138,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 ]
 				);

@@ -155,7 +159,7 @@ abstract class UserManager {

 		try {
 			$this->db->insert(
-				$this->dbTablePrefix . 'users',
+				$this->makeTableNameComponents('users'),
 				[
 					'email' => $email,
 					'password' => $password,
@@ -170,7 +174,7 @@ abstract class UserManager {
 			throw new UserAlreadyExistsException();
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

 		$newUserId = (int) $this->db->getLastInsertId();
@@ -182,6 +186,33 @@ abstract class UserManager {
 		return $newUserId;
 	}

+	/**
+	 * Updates the given user's password by setting it to the new specified password
+	 *
+	 * @param int $userId the ID of the user whose password should be updated
+	 * @param string $newPassword the new password
+	 * @throws UnknownIdException if no user with the specified ID has been found
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	protected function updatePasswordInternal($userId, $newPassword) {
+		$newPassword = \password_hash($newPassword, \PASSWORD_DEFAULT);
+
+		try {
+			$affected = $this->db->update(
+				$this->makeTableNameComponents('users'),
+				[ 'password' => $newPassword ],
+				[ 'id' => $userId ]
+			);
+
+			if ($affected === 0) {
+				throw new UnknownIdException();
+			}
+		}
+		catch (Error $e) {
+			throw new DatabaseError($e->getMessage());
+		}
+	}
+
 	/**
 	 * Called when a user has successfully logged in
 	 *
@@ -192,10 +223,11 @@ abstract class UserManager {
 	 * @param string $username the display name (if any) of the user
 	 * @param int $status the status of the user as one of the constants from the {@see Status} class
 	 * @param int $roles the roles of the user as a bitmask using constants from the {@see Role} class
+	 * @param int $forceLogout the counter that keeps track of forced logouts that need to be performed in the current session
 	 * @param bool $remembered whether the user has been remembered (instead of them having authenticated actively)
 	 * @throws AuthError if an internal problem occurred (do *not* catch)
 	 */
-	protected function onLoginSuccessful($userId, $email, $username, $status, $roles, $remembered) {
+	protected function onLoginSuccessful($userId, $email, $username, $status, $roles, $forceLogout, $remembered) {
 		// re-generate the session ID to prevent session fixation attacks (requests a cookie to be written on the client)
 		Session::regenerate(true);

@@ -206,6 +238,7 @@ abstract class UserManager {
 		$_SESSION[self::SESSION_FIELD_USERNAME] = $username;
 		$_SESSION[self::SESSION_FIELD_STATUS] = (int) $status;
 		$_SESSION[self::SESSION_FIELD_ROLES] = (int) $roles;
+		$_SESSION[self::SESSION_FIELD_FORCE_LOGOUT] = (int) $forceLogout;
 		$_SESSION[self::SESSION_FIELD_REMEMBERED] = $remembered;
 		$_SESSION[self::SESSION_FIELD_LAST_RESYNC] = \time();
 	}
@@ -227,12 +260,12 @@ 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 ]
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

 		if (empty($users)) {
@@ -314,7 +347,7 @@ abstract class UserManager {

 		try {
 			$this->db->insert(
-				$this->dbTablePrefix . 'users_confirmations',
+				$this->makeTableNameComponents('users_confirmations'),
 				[
 					'user_id' => (int) $userId,
 					'email' => $email,
@@ -325,7 +358,7 @@ abstract class UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

 		if (\is_callable($callback)) {
@@ -336,4 +369,86 @@ abstract class UserManager {
 		}
 	}

+	/**
+	 * Clears an existing directive that keeps the user logged in ("remember me")
+	 *
+	 * @param int $userId the ID of the user who shouldn't be kept signed in anymore
+	 * @param string $selector (optional) the selector which the deletion should be restricted to
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	protected function deleteRememberDirectiveForUserById($userId, $selector = null) {
+		$whereMappings = [];
+
+		if (isset($selector)) {
+			$whereMappings['selector'] = (string) $selector;
+		}
+
+		$whereMappings['user'] = (int) $userId;
+
+		try {
+			$this->db->delete(
+				$this->makeTableNameComponents('users_remembered'),
+				$whereMappings
+			);
+		}
+		catch (Error $e) {
+			throw new DatabaseError($e->getMessage());
+		}
+	}
+
+	/**
+	 * Triggers a forced logout in all sessions that belong to the specified user
+	 *
+	 * @param int $userId the ID of the user to sign out
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	protected function forceLogoutForUserById($userId) {
+		$this->deleteRememberDirectiveForUserById($userId);
+		$this->db->exec(
+			'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);
+	}
+
 }
--- a/tests/index.php
+++ b/tests/index.php
@@ -151,13 +151,12 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 							// do not keep logged in after session ends
 							$rememberDuration = null;
 						}
-						$auth->confirmEmailAndSignIn($_POST['selector'], $_POST['token'], $rememberDuration);
+
+						return $auth->confirmEmailAndSignIn($_POST['selector'], $_POST['token'], $rememberDuration);
 					}
 					else {
-						$auth->confirmEmail($_POST['selector'], $_POST['token']);
+						return $auth->confirmEmail($_POST['selector'], $_POST['token']);
 					}
-
-					return 'ok';
 				}
 				catch (\Delight\Auth\InvalidSelectorTokenPairException $e) {
 					return 'invalid token';
@@ -255,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';
@@ -383,8 +394,28 @@ function processRequestData(\Delight\Auth\Auth $auth) {

 				return 'ok';
 			}
-			else if ($_POST['action'] === 'logOutAndDestroySession') {
-				$auth->logOutAndDestroySession();
+			else if ($_POST['action'] === 'logOutEverywhereElse') {
+				try {
+					$auth->logOutEverywhereElse();
+				}
+				catch (\Delight\Auth\NotLoggedInException $e) {
+					return 'not logged in';
+				}
+
+				return 'ok';
+			}
+			else if ($_POST['action'] === 'logOutEverywhere') {
+				try {
+					$auth->logOutEverywhere();
+				}
+				catch (\Delight\Auth\NotLoggedInException $e) {
+					return 'not logged in';
+				}
+
+				return 'ok';
+			}
+			else if ($_POST['action'] === 'destroySession') {
+				$auth->destroySession();

 				return 'ok';
 			}
@@ -614,6 +645,43 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					return 'Username required';
 				}
 			}
+			else if ($_POST['action'] === 'admin.changePasswordForUser') {
+				if (isset($_POST['newPassword'])) {
+					if (isset($_POST['id'])) {
+						try {
+							$auth->admin()->changePasswordForUserById($_POST['id'], $_POST['newPassword']);
+						}
+						catch (\Delight\Auth\UnknownIdException $e) {
+							return 'unknown ID';
+						}
+						catch (\Delight\Auth\InvalidPasswordException $e) {
+							return 'invalid password';
+						}
+					}
+					elseif (isset($_POST['username'])) {
+						try {
+							$auth->admin()->changePasswordForUserByUsername($_POST['username'], $_POST['newPassword']);
+						}
+						catch (\Delight\Auth\UnknownUsernameException $e) {
+							return 'unknown username';
+						}
+						catch (\Delight\Auth\AmbiguousUsernameException $e) {
+							return 'ambiguous username';
+						}
+						catch (\Delight\Auth\InvalidPasswordException $e) {
+							return 'invalid password';
+						}
+					}
+					else {
+						return 'either ID or username required';
+					}
+				}
+				else {
+					return 'new password required';
+				}
+
+				return 'ok';
+			}
 			else {
 				throw new Exception('Unexpected action: ' . $_POST['action']);
 			}
@@ -771,9 +839,16 @@ function showAuthenticatedUserForm(\Delight\Auth\Auth $auth) {
 	echo '</form>';

 	echo '<form action="" method="post" accept-charset="utf-8">';
-	echo '<input type="hidden" name="action" value="logOutAndDestroySession" />';
-	echo '<button type="submit">Log out and destroy session</button>';
+	echo '<input type="hidden" name="action" value="logOutEverywhereElse" />';
+	echo '<button type="submit">Log out everywhere else</button>';
 	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="logOutEverywhere" />';
+	echo '<button type="submit">Log out everywhere</button>';
+	echo '</form>';
+
+	\showDestroySessionForm();
 }

 function showGuestUserForm() {
@@ -830,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>';

@@ -840,6 +920,8 @@ function showGuestUserForm() {
 	echo '<button type="submit">Can reset password?</button>';
 	echo '</form>';

+	\showDestroySessionForm();
+
 	echo '<h1>Administration</h1>';

 	echo '<form action="" method="post" accept-charset="utf-8">';
@@ -944,6 +1026,20 @@ function showGuestUserForm() {
 	echo '<input type="text" name="username" placeholder="Username" /> ';
 	echo '<button type="submit">Log in as user by username</button>';
 	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="admin.changePasswordForUser" />';
+	echo '<input type="text" name="id" placeholder="ID" /> ';
+	echo '<input type="text" name="newPassword" placeholder="New password" /> ';
+	echo '<button type="submit">Change password for user by ID</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="admin.changePasswordForUser" />';
+	echo '<input type="text" name="username" placeholder="Username" /> ';
+	echo '<input type="text" name="newPassword" placeholder="New password" /> ';
+	echo '<button type="submit">Change password for user by username</button>';
+	echo '</form>';
 }

 function showConfirmEmailForm() {
@@ -972,6 +1068,13 @@ function showConfirmEmailForm() {
 	echo '</form>';
 }

+function showDestroySessionForm() {
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="destroySession" />';
+	echo '<button type="submit">Destroy session</button>';
+	echo '</form>';
+}
+
 function createRolesOptions() {
 	$out = '';
Author	SHA1	Message	Date
Marco	729c76668f	Move all exceptions and errors to separate files for autoloading	2020-09-30 20:40:54 +02:00
Marco	cc6430a83e	Explain where usernames may be used to address unconfirmed recipients	2020-05-11 13:14:14 +02:00
Marco	6f933ac560	Explain how to impose restrictions on characters/length for usernames	2020-05-11 13:10:33 +02:00
Marco	157a7095b0	Use 'throttling' flag in 'Auth#forgotPassword' when limiting requests	2020-05-06 22:36:45 +02:00
Marco	0f976a260b	Fix doc comment for parameter 'ipAddress' on 'Auth' constructor	2020-05-06 22:35:20 +02:00
Marco	dcd893a12c	Document 'Auth#resetPasswordAndSignIn' in README	2020-04-20 21:36:08 +02:00
Marco	0086419175	Add tests for 'Auth#resetPasswordAndSignIn'	2020-04-20 21:35:04 +02:00
Marco	d49b35690c	Implement 'Auth#resetPasswordAndSignIn'	2020-04-20 21:34:00 +02:00
Marco	171519fdf3	Use 'see' tag to link 'Auth#id' to 'Auth#getUserId'	2020-04-20 21:32:43 +02:00
Marco	14ce7b1e8f	Add references between four methods for password reset via 'see' tags	2020-04-20 21:31:28 +02:00
Marco	49c70eff41	Document return value of 'Auth#resetPassword' in README	2020-04-20 21:02:57 +02:00
Marco	2f772b00c8	Adjust tests for 'Auth#resetPassword' now having a return value	2020-04-20 20:48:19 +02:00
Marco	5214da1f59	Make 'Auth#resetPassword' return both the user's ID and their email	2020-04-20 20:47:27 +02:00
Marco	d8847fb197	Document in README how to retrieve a list of all registered users	2020-03-19 18:52:24 +01:00
Emin Mühəmmədi	1757ad3fd1	Fix variable name in README	2019-07-28 17:44:37 +02:00
Marco	54f6c5320a	Refer to section 'Additional user information' from 'Registration'	2019-05-23 19:29:45 +02:00
Marco	4b3f2ab91c	Document option of custom expiry of requests for 'Auth#forgotPassword'	2019-02-25 19:52:32 +01:00
Marco	df990b5b75	Fix notes regarding session resync after adding or removing roles	2019-02-21 18:34:09 +01:00
Marco	7b2ac9b107	Fix missing entries in table of contents for 'Usage'	2019-01-29 13:33:07 +01:00
Marco	ad90c7d04a	Change responses with success messages from comments to 'echo'	2018-10-05 00:27:01 +02:00
Marco	c0baa517fa	Change responses with error messages from comments to 'die' statements	2018-10-04 23:55:55 +02:00
Marco	3120e3a6a5	Document return values of 'confirmEmail' and 'confirmEmailAndSignIn'	2018-10-04 23:12:41 +02:00
Marco	4cd6360fc7	Document optional database name, schema or other qualifier in README	2018-08-28 23:51:30 +02:00
Marco	382832457d	Make use of database name, schema or other qualifier in all statements	2018-08-28 23:44:50 +02:00
Marco	f70923679f	Implement methods 'makeTableName' and 'makeTableNameComponents'	2018-08-28 23:25:28 +02:00
Marco	521e73662d	Allow for specification of database name, schema or other qualifier	2018-08-28 22:03:40 +02:00
Marco	2b3bf611e2	Update dependencies	2018-08-28 21:47:16 +02:00
Marco	352260c759	Remove obsolete error class 'DatabaseDriverError'	2018-07-25 20:31:36 +02:00
Marco	cbf2b52f29	Fix wrong example of variable name for library's instance in README	2018-07-23 01:08:04 +02:00
Marco	c685f22937	Add note about scope of variables with regard to closures to README	2018-05-28 21:28:00 +02:00
Marco	9d08c939a0	Fail safely in role checks when invalid input has been supplied	2018-05-25 23:19:07 +02:00
Marco	7a8508d56e	Document effect of 'sessionResyncInterval' for affected operations	2018-04-26 18:12:30 +02:00
Marco	f6607f664d	Enhance 'DatabaseError' instances to be more verbose	2018-04-20 18:01:00 +02:00
Marco	49a4ef8280	Document required database privileges in README	2018-04-03 14:48:10 +02:00
Marco	50c284fff7	Document method 'logOutEverywhereElse' from class 'Auth'	2018-03-25 05:34:37 +02:00
Marco	83c74689a3	Document method 'logOutEverywhere' from class 'Auth'	2018-03-25 05:32:32 +02:00
Marco	6d34606336	Update documentation on how to destroy the entire session	2018-03-25 05:29:13 +02:00
Marco	be5b744470	Explain new return values of 'confirmEmail' (etc.) in migration guide	2018-03-25 05:11:45 +02:00
Marco	4f6692bd25	Also test return values of 'confirmEmail' and 'confirmEmailAndSignIn'	2018-03-25 04:58:24 +02:00
Marco	0f8116e654	Also return old email from 'confirmEmail' and 'confirmEmailAndSignIn'	2018-03-25 04:55:58 +02:00
Marco	25f7a8908d	Force logout in any open sessions when a user resets their password	2018-03-25 03:42:36 +02:00
Marco	a7c1ebcc9f	Force logout in any other sessions when a user changes their password	2018-03-25 03:40:57 +02:00
Marco	71ce2b58c9	Force logout for users when administrators change their passwords	2018-03-25 03:38:12 +02:00
Marco	4c4c4c23f6	Explain removal of 'logOutAndDestroySession' in migration guide	2018-03-25 01:40:49 +01:00
Marco	00a8a49f17	Test method 'destroySession' instead of 'logOutAndDestroySession'	2018-03-25 01:40:16 +01:00
Marco	9f71eff176	Remove method 'logOutAndDestroySession' from class 'Auth'	2018-03-25 01:28:35 +01:00
Marco	fdd95e8b89	Improve language	2018-03-25 01:10:29 +01:00
Marco	73b9232f63	Add tests for method 'logOutEverywhereElse' from class 'Auth'	2018-03-25 01:08:36 +01:00
Marco	20f484567a	Implement method 'logOutEverywhereElse' in class 'Auth'	2018-03-25 01:07:40 +01:00
Marco	79c5a4f6d5	Add tests for method 'logOutEverywhere' from class 'Auth'	2018-03-25 00:31:02 +01:00
Marco	3ae1769256	Implement method 'logOutEverywhere' in class 'Auth'	2018-03-25 00:28:21 +01:00
Marco	58f1f34593	Implement method 'forceLogoutForUserById' in class 'UserManager'	2018-03-24 23:39:03 +01:00
Marco	4d7b66ee5a	When performing normal logout only delete local remember directives	2018-03-24 23:31:12 +01:00
Marco	62270a2c48	Permit restriction to selector in 'deleteRememberDirectiveForUserById'	2018-03-24 23:13:04 +01:00
Marco	9848082bbb	Implement method 'getRememberDirectiveExpiry' in class 'Auth'	2018-03-24 23:09:18 +01:00
Marco	29afbdfc93	Implement method 'getRememberDirectiveSelector' in class 'Auth'	2018-03-24 23:02:01 +01:00
Marco	62f4b39dcf	Perform logout for user whenever 'force_logout' has been incremented	2018-03-24 18:15:21 +01:00
Marco	235008fdb8	Improve order of statements	2018-03-24 18:12:33 +01:00
Marco	adc1d73539	Store and manage 'force_logout' value from 'users' table in session	2018-03-24 18:04:06 +01:00
Marco	c3d44eab3e	Describe required changes to database schemas in migration guide	2018-03-24 17:54:49 +01:00
Marco	ade63d07df	Add 'force_logout' column to 'users' table in database schema	2018-03-24 17:49:35 +01:00
Marco	d9297709af	Prepare migration guide for next major version	2018-03-24 17:46:04 +01:00
Marco	7be05ddde2	Improve documentation	2018-03-24 17:44:42 +01:00
Marco	095b8ccc70	Document 'changePasswordForUserById' from class 'Administration'	2018-03-21 03:24:06 +01:00
Marco	550a6d0355	Add tests for 'changePasswordForUserById' from class 'Administration'	2018-03-21 03:22:29 +01:00
Marco	c494e0fa13	Throw 'UnknownIdException' in 'updatePasswordInternal' when no matches	2018-03-21 03:20:11 +01:00
Marco	d7d9899167	Use 'changePasswordForUserById' for 'changePasswordForUserByUsername'	2018-03-21 02:55:31 +01:00
Marco	05165a44a6	Implement method 'changePasswordForUserById' in class 'Administration'	2018-03-21 02:54:50 +01:00
Marco	c3f2097750	Document 'changePasswordForUserByUsername' from 'Administration'	2018-03-21 02:35:09 +01:00
Marco	395a065fd4	Add tests for 'changePasswordForUserByUsername' from 'Administration'	2018-03-21 02:28:55 +01:00
Marco	627c592891	Let 'Administration' constructor be part of public API	2018-03-20 16:13:56 +01:00
Marco	2a6d1c4f7d	Delete 'remember me' directives in 'changePasswordForUserByUsername'	2018-03-20 16:11:56 +01:00
Marco	a63e5ec053	Move essence of 'deleteRememberDirectiveForUserById' to 'UserManager'	2018-03-20 16:09:25 +01:00
Marco	4115340927	Improve language	2018-03-20 16:04:29 +01:00
Marco	09dac6a5f5	Rename method 'deleteRememberDirective' in class 'Auth' Use more expressive name 'deleteRememberDirectiveForUserById'	2018-03-20 15:57:37 +01:00
Marco	3a7a860c6d	Validate password in 'changePasswordForUserByUsername' for consistency	2018-03-20 15:54:19 +01:00
maxsenft	131aea3ded	Implement method 'changePasswordForUserByUsername' in 'Administration'	2018-03-20 15:50:44 +01:00
maxsenft	e14f3d1925	Rename method 'updatePassword' to 'updatePasswordInternal'	2018-03-20 15:45:25 +01:00
maxsenft	1d54ff2f6b	Move 'updatePassword' method from class 'Auth' to class 'UserManager'	2018-03-20 15:41:57 +01:00
maxsenft	ec6afdad48	Accept 'PdoDsn' and 'PDO' as well in 'Administration' constructor	2018-03-20 15:38:35 +01:00
Marco	58e69fdd0e	Do not pass 'null' to 'count' which triggers a warning since PHP 7.2	2018-03-15 23:32:15 +01:00