Enhance 'DatabaseError' instances to be more verbose

Document required database privileges in README
Document method 'logOutEverywhereElse' from class 'Auth'
2025-08-07 08:36:28 +02:00 · 2018-04-20 18:01:00 +02:00 · 2018-04-03 14:48:10 +02:00 · 2018-03-25 05:34:37 +02:00 · 2018-03-25 05:32:32 +02:00 · 2018-03-25 05:29:13 +02:00
12 changed files with 1651 additions and 534 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
@@ -0,0 +1,58 @@
+-- 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)
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS "users" (
+	"id" SERIAL PRIMARY KEY CHECK ("id" >= 0),
+	"email" VARCHAR(249) UNIQUE NOT NULL,
+	"password" VARCHAR(255) NOT NULL,
+	"username" VARCHAR(100) DEFAULT NULL,
+	"status" SMALLINT NOT NULL DEFAULT '0' CHECK ("status" >= 0),
+	"verified" SMALLINT NOT NULL DEFAULT '0' CHECK ("verified" >= 0),
+	"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),
+	"force_logout" INTEGER NOT NULL DEFAULT '0' CHECK ("force_logout" >= 0)
+);
+
+CREATE TABLE IF NOT EXISTS "users_confirmations" (
+	"id" SERIAL PRIMARY KEY CHECK ("id" >= 0),
+	"user_id" INTEGER NOT NULL CHECK ("user_id" >= 0),
+	"email" VARCHAR(249) NOT NULL,
+	"selector" VARCHAR(16) UNIQUE NOT NULL,
+	"token" VARCHAR(255) NOT NULL,
+	"expires" INTEGER NOT NULL CHECK ("expires" >= 0)
+);
+CREATE INDEX IF NOT EXISTS "email_expires" ON "users_confirmations" ("email", "expires");
+CREATE INDEX IF NOT EXISTS "user_id" ON "users_confirmations" ("user_id");
+
+CREATE TABLE IF NOT EXISTS "users_remembered" (
+	"id" BIGSERIAL PRIMARY KEY CHECK ("id" >= 0),
+	"user" INTEGER NOT NULL CHECK ("user" >= 0),
+	"selector" VARCHAR(24) UNIQUE NOT NULL,
+	"token" VARCHAR(255) NOT NULL,
+	"expires" INTEGER NOT NULL CHECK ("expires" >= 0)
+);
+CREATE INDEX IF NOT EXISTS "user" ON "users_remembered" ("user");
+
+CREATE TABLE IF NOT EXISTS "users_resets" (
+	"id" BIGSERIAL PRIMARY KEY CHECK ("id" >= 0),
+	"user" INTEGER NOT NULL CHECK ("user" >= 0),
+	"selector" VARCHAR(20) UNIQUE NOT NULL,
+	"token" VARCHAR(255) NOT NULL,
+	"expires" INTEGER NOT NULL CHECK ("expires" >= 0)
+);
+CREATE INDEX IF NOT EXISTS "user_expires" ON "users_resets" ("user", "expires");
+
+CREATE TABLE IF NOT EXISTS "users_throttling" (
+	"bucket" VARCHAR(44) PRIMARY KEY,
+	"tokens" REAL NOT NULL CHECK ("tokens" >= 0),
+	"replenished_at" INTEGER NOT NULL CHECK ("replenished_at" >= 0),
+	"expires_at" INTEGER NOT NULL CHECK ("expires_at" >= 0)
+);
+CREATE INDEX IF NOT EXISTS "expires_at" ON "users_throttling" ("expires_at");
+
+COMMIT;
--- 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,8 @@
 # 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)
 * [From `v3.x.x` to `v4.x.x`](#from-v3xx-to-v4xx)
@@ -9,11 +11,86 @@

 ## General

-Update your version of this library via Composer [[?]](https://github.com/delight-im/Knowledge/blob/master/Composer%20(PHP).md):
+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).

-```
-$ composer update delight-im/auth
-```
+## 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`.
+
+ * The second argument of the `Auth` constructor, which was named `$useHttps`, has been removed. If you previously had it set to `true`, make sure to set the value of the `session.cookie_secure` directive to `1` now. You may do so either directly in your [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`), via the `\ini_set` method or via the `\session_set_cookie_params` method. Otherwise, make sure that directive is set to `0`.
+
+ * The third argument of the `Auth` constructor, which was named `$allowCookiesScriptAccess`, has been removed. If you previously had it set to `true`, make sure to set the value of the `session.cookie_httponly` directive to `0` now. You may do so either directly in your [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`), via the `\ini_set` method or via the `\session_set_cookie_params` method. Otherwise, make sure that directive is set to `1`.
+
+ * Only if *both* of the following two conditions are met:
+
+   * The directive `session.cookie_domain` is set to an empty value. It may have been set directly in your [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`), via the `\ini_set` method or via the `\session_set_cookie_params` method. You can check the value of that directive by executing the following statement somewhere in your application:
+
+     ```php
+     \var_dump(\ini_get('session.cookie_domain'));
+     ```
+
+   * Your application is accessed via a registered or registrable *domain name*, either by yourself during development and testing or by your visitors and users in production. That means your application is *not*, or *not only*, accessed via `localhost` or via an IP address.
+
+   Then the domain scope for the [two cookies](README.md#cookies) used by this library has changed. You can handle this change in one of two different ways:
+
+   * Restore the old behavior by placing the following statement as early as possible in your application, and before you create the `Auth` instance:
+
+     ```php
+     \ini_set('session.cookie_domain', \preg_replace('/^www\./', '', $_SERVER['HTTP_HOST']));
+     ```
+
+     You may also evaluate the complete second parameter and put its value directly into your [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`).
+
+   * Use the new domain scope for your application. To do so, you only need to [rename the cookies](README.md#renaming-the-librarys-cookies) used by this library in order to prevent conflicts with old cookies that have been created previously. Renaming the cookies is critically important here. We recommend a versioned name such as `session_v1` for the session cookie.
+
+ * Only if *both* of the following two conditions are met:
+
+   * The directive `session.cookie_domain` is set to a value that starts with the `www` subdomain. It may have been set directly in your [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`), via the `\ini_set` method or via the `\session_set_cookie_params` method. You can check the value of that directive by executing the following statement somewhere in your application:
+
+     ```php
+     \var_dump(\ini_get('session.cookie_domain'));
+     ```
+
+   * Your application is accessed via a registered or registrable *domain name*, either by yourself during development and testing or by your visitors and users in production. That means your application is *not*, or *not only*, accessed via `localhost` or via an IP address.
+
+   Then the domain scope for [one of the cookies](README.md#cookies) used by this library has changed. To make your application work correctly with the new scope, [rename the cookies](README.md#renaming-the-librarys-cookies) used by this library in order to prevent conflicts with old cookies that have been created previously. Renaming the cookies is critically important here. We recommend a versioned name such as `session_v1` for the session cookie.
+
+ * If the directive `session.cookie_path` is set to an empty value, then the path scope for [one of the cookies](README.md#cookies) used by this library has changed. To make your application work correctly with the new scope, [rename the cookies](README.md#renaming-the-librarys-cookies) used by this library in order to prevent conflicts with old cookies that have been created previously. Renaming the cookies is critically important here. We recommend a versioned name such as `session_v1` for the session cookie.
+
+   The directive may have been set directly in your [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`), via the `\ini_set` method or via the `\session_set_cookie_params` method. You can check the value of that directive by executing the following statement somewhere in your application:
+
+   ```php
+   \var_dump(\ini_get('session.cookie_path'));
+   ```

 ## From `v5.x.x` to `v6.x.x`

--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Auth

-Authentication for PHP. Simple, lightweight and secure.
+**Authentication for PHP. Simple, lightweight and secure.**

 Written once, to be used everywhere.

@@ -8,7 +8,7 @@ Completely framework-agnostic and database-agnostic.

 ## Why do I need this?

- * There are [tons](http://www.troyhunt.com/2011/01/whos-who-of-bad-password-practices.html) [of](http://www.jeremytunnell.com/posts/swab-password-policies-and-two-factor-authentication-a-comedy-of-errors) [websites](http://badpasswordpolicies.tumblr.com/) with weak authentication systems. Don't build such a site.
+ * There are [tons](http://www.troyhunt.com/2011/01/whos-who-of-bad-password-practices.html) [of](http://www.jeremytunnell.com/posts/swab-password-policies-and-two-factor-authentication-a-comedy-of-errors) [websites](http://badpasswordpolicies.tumblr.com/) with weak authentication systems. Don’t build such a site.
 * Re-implementing a new authentication system for every PHP project is *not* a good idea.
 * Building your own authentication classes piece by piece, and copying it to every project, is *not* recommended, either.
 * A secure authentication system with an easy-to-use API should be thoroughly designed and planned.
@@ -18,9 +18,9 @@ Completely framework-agnostic and database-agnostic.

 * PHP 5.6.0+
   * PDO (PHP Data Objects) extension (`pdo`)
-     * MySQL Native Driver (`mysqlnd`) **or** SQLite driver (`sqlite`)
+     * MySQL Native Driver (`mysqlnd`) **or** PostgreSQL driver (`pgsql`) **or** SQLite driver (`sqlite`)
   * OpenSSL extension (`openssl`)
- * MySQL 5.5.3+ **or** MariaDB 5.5.23+ **or** SQLite 3.14.1+ **or** other SQL databases that you create the [schema](Database) for
+ * MySQL 5.5.3+ **or** MariaDB 5.5.23+ **or** PostgreSQL 9.5.10+ **or** SQLite 3.14.1+ **or** [other SQL databases](Database)

 ## Installation

@@ -38,7 +38,9 @@ Completely framework-agnostic and database-agnostic.

 1. Set up a database and create the required tables:

+    * [MariaDB](Database/MySQL.sql)
    * [MySQL](Database/MySQL.sql)
+    * [PostgreSQL](Database/PostgreSQL.sql)
    * [SQLite](Database/SQLite.sql)

 ## Upgrading
@@ -52,9 +54,9 @@ Migrating from an earlier version of this project? See our [upgrade guide](Migra
 * [Login (sign in)](#login-sign-in)
 * [Email verification](#email-verification)
 * [Keeping the user logged in](#keeping-the-user-logged-in)
- * [Password reset ("forgot password")](#password-reset-forgot-password)
- * [Changing the current user's password](#changing-the-current-users-password)
- * [Changing the current user's email address](#changing-the-current-users-email-address)
+ * [Password reset (“forgot password”)](#password-reset-forgot-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)
 * [Logout](#logout)
 * [Accessing user information](#accessing-user-information)
@@ -62,10 +64,10 @@ 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)
-   * [Checking whether the user was "remembered"](#checking-whether-the-user-was-remembered)
+   * [Checking whether the user was “remembered”](#checking-whether-the-user-was-remembered)
   * [IP address](#ip-address)
   * [Additional user information](#additional-user-information)
- * [Reconfirming the user's password](#reconfirming-the-users-password)
+ * [Reconfirming the user’s password](#reconfirming-the-users-password)
 * [Roles (or groups)](#roles-or-groups)
   * [Checking roles](#checking-roles)
   * [Available roles](#available-roles)
@@ -79,6 +81,14 @@ Migrating from an earlier version of this project? See our [upgrade guide](Migra
   * [Assigning roles to users](#assigning-roles-to-users)
   * [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)
+   * [Restricting the path where cookies are available](#restricting-the-path-where-cookies-are-available)
+   * [Controlling client-side script access to cookies](#controlling-client-side-script-access-to-cookies)
+   * [Configuring transport security for cookies](#configuring-transport-security-for-cookies)
 * [Utilities](#utilities)
   * [Creating a random string](#creating-a-random-string)
   * [Creating a UUID v4 as per RFC 4122](#creating-a-uuid-v4-as-per-rfc-4122)
@@ -87,28 +97,32 @@ Migrating from an earlier version of this project? See our [upgrade guide](Migra
 ### Creating a new instance

 ```php
-// $db = new PDO('mysql:dbname=my-database;host=localhost;charset=utf8mb4', 'my-username', 'my-password');
+// $db = new \PDO('mysql:dbname=my-database;host=localhost;charset=utf8mb4', 'my-username', 'my-password');
 // or
-// $db = new PDO('sqlite:../Databases/my-database.sqlite');
+// $db = new \PDO('pgsql:dbname=my-database;host=localhost;port=5432', 'my-username', 'my-password');
+// or
+// $db = new \PDO('sqlite:../Databases/my-database.sqlite');

 // or

 // $db = new \Delight\Db\PdoDsn('mysql:dbname=my-database;host=localhost;charset=utf8mb4', 'my-username', 'my-password');
 // or
+// $db = new \Delight\Db\PdoDsn('pgsql:dbname=my-database;host=localhost;port=5432', 'my-username', 'my-password');
+// or
 // $db = new \Delight\Db\PdoDsn('sqlite:../Databases/my-database.sqlite');

 $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 you do enforce HTTPS on your site, pass `true` as the second parameter to the constructor. This is optional and the default is `false`.
+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.

-Only in the very rare case that you need access to your cookies from JavaScript, pass `true` as the third argument to the constructor. This is optional and the default is `false`. There is almost always a *better* solution than enabling this, however.
+Should your database tables for this library need a common prefix, e.g. `my_users` instead of `users` (and likewise for the other tables), pass the prefix (e.g. `my_`) as the third parameter to the constructor, which is named `$dbTablePrefix`. This is optional and the prefix is empty by default.

-If your web server is behind a proxy server and `$_SERVER['REMOTE_ADDR']` only contains the proxy's IP address, you must pass the user's real IP address to the constructor in the fourth argument. The default is `null`.
+During development, you may want to disable the request limiting or throttling performed by this library. To do so, pass `false` to the constructor as the fourth argument, which is named `$throttling`. The feature is enabled by default.

-Should your database tables for this library need a common prefix, e.g. `my_users` instead of `users` (and likewise for the other tables), pass the prefix (e.g. `my_`) as the fifth parameter to the constructor. This is optional and the prefix is empty by default.
+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`.

 ### Registration (sign up)

@@ -134,17 +148,17 @@ catch (\Delight\Auth\TooManyRequestsException $e) {
 }
 ```

-The username in the third parameter is optional. You can pass `null` there if you don't want to manage usernames.
+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`.

 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);
+$url = 'https://www.example.com/verify_email?selector=' . \urlencode($selector) . '&token=' . \urlencode($token);
 ```

-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.
+If you don’t want to perform email verification, just omit the last parameter to `Auth#register`. The new user will be active immediately, then.

 ### Login (sign in)

@@ -168,7 +182,7 @@ catch (\Delight\Auth\TooManyRequestsException $e) {
 }
 ```

-If you want to sign in with usernames on the other hand, either in addition to the login via email address or as a replacement, that's possible as well. Simply call the method `loginWithUsername` instead of method `login`. Then, instead of catching `InvalidEmailException`, make sure to catch both `UnknownUsernameException` and `AmbiguousUsernameException`. You may also want to read the notes about the uniqueness of usernames in the section that explains how to [sign up new users](#registration-sign-up).
+If you want to sign in with usernames on the other hand, either in addition to the login via email address or as a replacement, that’s possible as well. Simply call the method `loginWithUsername` instead of method `login`. Then, instead of catching `InvalidEmailException`, make sure to catch both `UnknownUsernameException` and `AmbiguousUsernameException`. You may also want to read the notes about the uniqueness of usernames in the section that explains how to [sign up new users](#registration-sign-up).

 ### Email verification

@@ -198,7 +212,7 @@ If you want the user to be automatically signed in after successful confirmation

 ### Keeping the user logged in

-The third parameter to the `Auth#login` method 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.
+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.

 ```php
 if ($_POST['remember'] == 1) {
@@ -219,9 +233,11 @@ $auth->login($_POST['email'], $_POST['password'], $rememberDuration);

 *Without* the persistent login, which is the *default* behavior, a user will only stay logged in until they close their browser, or as long as configured via `session.cookie_lifetime` and `session.gc_maxlifetime` in PHP.

-Omit the third parameter or set it to `null` to disable the feature. Otherwise, you may ask the user whether they want to enable "remember me". This is usually done with a checkbox in your user interface. Use the input from that checkbox to decide between `null` and a pre-defined duration in seconds here, e.g. `60 * 60 * 24 * 365.25` for one year.
+Omit the third parameter or set it to `null` to disable the feature. Otherwise, you may ask the user whether they want to enable “remember me”. This is usually done with a checkbox in your user interface. Use the input from that checkbox to decide between `null` and a pre-defined duration in seconds here, e.g. `60 * 60 * 24 * 365.25` for one year.

-### Password reset ("forgot password")
+### Password reset (“forgot password”)
+
+#### Step 1 of 3: Initiating the request

 ```php
 try {
@@ -248,15 +264,42 @@ catch (\Delight\Auth\TooManyRequestsException $e) {
 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);
+$url = 'https://www.example.com/reset_password?selector=' . \urlencode($selector) . '&token=' . \urlencode($token);
 ```

+#### 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.

 If the selector/token pair is valid, let the user choose a new password:

 ```php
-if ($auth->canResetPassword($_POST['selector'], $_POST['token'])) {
+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)
+
+    // ask the user for their new password
+}
+catch (\Delight\Auth\InvalidSelectorTokenPairException $e) {
+    // invalid token
+}
+catch (\Delight\Auth\TokenExpiredException $e) {
+    // token expired
+}
+catch (\Delight\Auth\ResetDisabledException $e) {
+    // password reset is disabled
+}
+catch (\Delight\Auth\TooManyRequestsException $e) {
+    // too many requests
+}
+```
+
+Alternatively, if you don’t need any error messages but only want to check the validity, you can use the slightly simpler version:
+
+```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)

@@ -264,6 +307,8 @@ if ($auth->canResetPassword($_POST['selector'], $_POST['token'])) {
 }
 ```

+#### Step 3 of 3: Updating the password
+
 Now when you have the new password for the user (and still have the other two pieces of information), you can reset the password:

 ```php
@@ -289,7 +334,7 @@ catch (\Delight\Auth\TooManyRequestsException $e) {
 }
 ```

-### Changing the current user's password
+### Changing the current user’s password

 If a user is currently logged in, they may change their password.

@@ -312,33 +357,26 @@ catch (\Delight\Auth\TooManyRequestsException $e) {

 Asking the user for their current (and soon *old*) password and requiring it for verification is the recommended way to handle password changes. This is shown above.

-If you’re sure that you don’t need that confirmation, however, you may use the following method instead:
+If you’re sure that you don’t need that confirmation, however, you may call `changePasswordWithoutOldPassword` instead of `changePassword` and drop the first parameter from that method call (which would otherwise contain the old password).

-```php
-try {
-    $auth->changePasswordWithoutOldPassword($_POST['newPassword']);
+In any case, after the user’s password has been changed, you should send an email to their account’s primary email address as an out-of-band notification informing the account owner about this critical change.

-    // password has been changed
-}
-catch (\Delight\Auth\NotLoggedInException $e) {
-    // not logged in
-}
-catch (\Delight\Auth\InvalidPasswordException $e) {
-    // invalid password
-}
-```
-
-### Changing the current user's email address
+### Changing the current user’s email address

 If a user is currently logged in, they may change their email address.

 ```php
 try {
-    $auth->changeEmail($_POST['newEmail'], function ($selector, $token) {
-        // send `$selector` and `$token` to the user (e.g. via email)
-    });
+    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)
+        });

-    // the change will take effect as soon as the email address has been confirmed
+        // 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
+    }
 }
 catch (\Delight\Auth\InvalidEmailException $e) {
    // invalid email address
@@ -360,9 +398,11 @@ catch (\Delight\Auth\TooManyRequestsException $e) {
 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);
+$url = 'https://www.example.com/verify_email?selector=' . \urlencode($selector) . '&token=' . \urlencode($token);
 ```

+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.
+
 ### 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:
@@ -404,15 +444,37 @@ catch (\Delight\Auth\TooManyRequestsException $e) {
 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);
+$url = 'https://www.example.com/verify_email?selector=' . \urlencode($selector) . '&token=' . \urlencode($token);
 ```

 ### Logout

 ```php
-$auth->logout();
+$auth->logOut();

-// user has been signed out
+// or
+
+try {
+    $auth->logOutEverywhereElse();
+}
+catch (\Delight\Auth\NotLoggedInException $e) {
+    // not logged in
+}
+
+// or
+
+try {
+    $auth->logOutEverywhere();
+}
+catch (\Delight\Auth\NotLoggedInException $e) {
+    // 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();
 ```

 ### Accessing user information
@@ -486,7 +548,7 @@ if ($auth->isSuspended()) {
 }
 ```

-#### Checking whether the user was "remembered"
+#### Checking whether the user was “remembered”

 ```php
 if ($auth->isRemembered()) {
@@ -507,13 +569,13 @@ $ip = $auth->getIpAddress();

 #### Additional user information

-In order to preserve this library's suitability for all purposes as well as its full re-usability, it doesn't come with additional bundled columns for user information. But you don't have to do without additional user information, of course:
+In order to preserve this library’s suitability for all purposes as well as its full re-usability, it doesn’t come with additional bundled columns for user information. But you don’t have to do without additional user information, of course:

-Here's how to use this library with your own tables for custom user information in a maintainable and re-usable way:
+Here’s how to use this library with your own tables for custom user information in a maintainable and re-usable way:

 1. Add any number of custom database tables where you store custom user information, e.g. a table named `profiles`.
- 1. Whenever you call the `register` method (which returns the new user's ID), add your own logic afterwards that fills your custom database tables.
- 1. If you need the custom user information only rarely, you may just retrieve it as needed. If you need it more frequently, however, you'd probably want to have it in your session data. The following method is how you can load and access your data in a reliable way:
+ 1. Whenever you call the `register` method (which returns the new user’s ID), add your own logic afterwards that fills your custom database tables.
+ 1. If you need the custom user information only rarely, you may just retrieve it as needed. If you need it more frequently, however, you’d probably want to have it in your session data. The following method is how you can load and access your data in a reliable way:

    ```php
    function getUserInfo(\Delight\Auth\Auth $auth) {
@@ -530,7 +592,7 @@ Here's how to use this library with your own tables for custom user information
    }
    ```

-### Reconfirming the user's password
+### Reconfirming the user’s password

 Whenever you want to confirm the user’s identity again, e.g. before the user is allowed to perform some “dangerous” action, you should verify their password again to confirm that they actually are who they claim to be.

@@ -581,6 +643,12 @@ if ($auth->hasAllRoles(\Delight\Auth\Role::DEVELOPER, \Delight\Auth\Role::MANAGE

 While the method `hasRole` takes exactly one role as its argument, the two methods `hasAnyRole` and `hasAllRoles` can take any number of roles that you would like to check for.

+Alternatively, you can get a list of all the roles that have been assigned to the user:
+
+```php
+$auth->getRoles();
+```
+
 #### Available roles

 ```php
@@ -608,11 +676,19 @@ While the method `hasRole` takes exactly one role as its argument, the two metho
 \Delight\Auth\Role::TRANSLATOR;
 ```

-You can use any of these roles and ignore those that you don't need.
+You can use any of these roles and ignore those that you don’t need. The list above can also be retrieved programmatically, in one of three formats:
+
+```php
+\Delight\Auth\Role::getMap();
+// or
+\Delight\Auth\Role::getNames();
+// or
+\Delight\Auth\Role::getValues();
+```

 #### Permissions (or access rights, privileges or capabilities)

-The permissions of each user are encoded in the way that role requirements are specified throughout your code base. If those requirements are evaluated with a specific user's set of roles, implicitly checked permissions are the result.
+The permissions of each user are encoded in the way that role requirements are specified throughout your code base. If those requirements are evaluated with a specific user’s set of roles, implicitly checked permissions are the result.

 For larger projects, it is often recommended to maintain the definition of permissions in a single place. You then don’t check for *roles* in your business logic, but you check for *individual permissions*. You could implement that concept as follows:

@@ -694,13 +770,21 @@ You may provide security-conscious (and experienced) users with the possibility

 ```php
 try {
-    $auth->setPasswordResetEnabled($_POST['enabled'] == 1);
+    if ($auth->reconfirmPassword($_POST['password'])) {
+        $auth->setPasswordResetEnabled($_POST['enabled'] == 1);

-    // the settings have been changed
+        // the setting has been changed
+    }
+    else {
+        // we can't say if the user is who they claim to be
+    }
 }
 catch (\Delight\Auth\NotLoggedInException $e) {
    // the user is not signed in
 }
+catch (\Delight\Auth\TooManyRequestsException $e) {
+    // too many requests
+}
 ```

 In order to check the current value of this setting, use the return value from
@@ -769,7 +853,7 @@ catch (\Delight\Auth\UserAlreadyExistsException $e) {
 }
 ```

-The username in the third parameter is optional. You can pass `null` there if you don't want to manage usernames.
+The username in the third parameter is optional. You can pass `null` there if you don’t want to manage usernames.

 If you want to enforce unique usernames, on the other hand, simply call `createUserWithUniqueUsername` instead of `createUser`, and be prepared to catch the `DuplicateUsernameException`.

@@ -891,6 +975,214 @@ catch (\Delight\Auth\UnknownIdException $e) {
 }
 ```

+Alternatively, you can get a list of all the roles that have been assigned to the user:
+
+```php
+$auth->admin()->getRolesForUserById($userId);
+```
+
+#### Impersonating users (logging in as user)
+
+```php
+try {
+    $auth->admin()->logInAsUserById($_POST['id']);
+}
+catch (\Delight\Auth\UnknownIdException $e) {
+    // unknown ID
+}
+catch (\Delight\Auth\EmailNotVerifiedException $e) {
+    // email address not verified
+}
+
+// or
+
+try {
+    $auth->admin()->logInAsUserByEmail($_POST['email']);
+}
+catch (\Delight\Auth\InvalidEmailException $e) {
+    // unknown email address
+}
+catch (\Delight\Auth\EmailNotVerifiedException $e) {
+    // email address not verified
+}
+
+// or
+
+try {
+    $auth->admin()->logInAsUserByUsername($_POST['username']);
+}
+catch (\Delight\Auth\UnknownUsernameException $e) {
+    // unknown username
+}
+catch (\Delight\Auth\AmbiguousUsernameException $e) {
+    // ambiguous username
+}
+catch (\Delight\Auth\EmailNotVerifiedException $e) {
+    // email address not verified
+}
+```
+
+#### Changing a user’s password
+
+```php
+try {
+    $auth->admin()->changePasswordForUserById($_POST['id'], $_POST['newPassword']);
+}
+catch (\Delight\Auth\UnknownIdException $e) {
+    // unknown ID
+}
+catch (\Delight\Auth\InvalidPasswordException $e) {
+    // invalid password
+}
+
+// or
+
+try {
+    $auth->admin()->changePasswordForUserByUsername($_POST['username'], $_POST['newPassword']);
+}
+catch (\Delight\Auth\UnknownUsernameException $e) {
+    // unknown username
+}
+catch (\Delight\Auth\AmbiguousUsernameException $e) {
+    // ambiguous username
+}
+catch (\Delight\Auth\InvalidPasswordException $e) {
+    // invalid password
+}
+```
+
+### Cookies
+
+This library uses two cookies to keep state on the client: The first, whose name you can retrieve using
+
+```php
+\session_name();
+```
+
+is the general (mandatory) session cookie. The second (optional) cookie is only used for [persistent logins](#keeping-the-user-logged-in) and its name can be retrieved as follows:
+
+```php
+\Delight\Auth\Auth::createRememberCookieName();
+```
+
+#### Renaming the library’s cookies
+
+You can rename the session cookie used by this library through one of the following means, in order of recommendation:
+
+ * In the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`), find the line with the `session.name` directive and change its value to something like `session_v1`, as in:
+
+   ```
+   session.name = session_v1
+   ```
+
+ * As early as possible in your application, and before you create the `Auth` instance, call `\ini_set` to change `session.name` to something like `session_v1`, as in:
+
+   ```php
+   \ini_set('session.name', 'session_v1');
+   ```
+
+   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`).
+
+ * As early as possible in your application, and before you create the `Auth` instance, call `\session_name` with an argument like `session_v1`, as in:
+
+   ```php
+   \session_name('session_v1');
+   ```
+
+   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`).
+
+The name of the cookie for [persistent logins](#keeping-the-user-logged-in) will change as well – automatically – following your change of the session cookie’s name.
+
+#### Defining the domain scope for cookies
+
+A cookie’s `domain` attribute controls which domain (and which subdomains) the cookie will be valid for, and thus where the user’s session and authentication state will be available.
+
+The recommended default is an empty string, which means that the cookie will only be valid for the *exact* current host, *excluding* any subdomains that may exist. You should only use a different value if you need to share cookies between different subdomains. Often, you’ll want to share cookies between the bare domain and the `www` subdomain, but you might also want to share them between any other set of subdomains.
+
+Whatever set of subdomains you choose, you should set the cookie’s attribute to the *most specific* domain name that still includes all your required subdomains. For example, to share cookies between `example.com` and `www.example.com`, you would set the attribute to `example.com`. But if you wanted to share cookies between `sub1.app.example.com` and `sub2.app.example.com`, you should set the attribute to `app.example.com`. Any explicitly specified domain name will always *include* all subdomains that may exist.
+
+You can change the attribute through one of the following means, in order of recommendation:
+
+ * In the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`), find the line with the `session.cookie_domain` directive and change its value as desired, e.g.:
+
+   ```
+   session.cookie_domain = example.com
+   ```
+
+ * As early as possible in your application, and before you create the `Auth` instance, call `\ini_set` to change the value of the `session.cookie_domain` directive as desired, e.g.:
+
+   ```php
+   \ini_set('session.cookie_domain', 'example.com');
+   ```
+
+   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`).
+
+#### Restricting the path where cookies are available
+
+A cookie’s `path` attribute controls which directories (and subdirectories) the cookie will be valid for, and thus where the user’s session and authentication state will be available.
+
+In most cases, you’ll want to make cookies available for all paths, i.e. any directory and file, starting in the root directory. That is what a value of `/` for the attribute does, which is also the recommended default. You should only change this attribute to a different value, e.g. `/path/to/subfolder`, if you want to restrict which directories your cookies will be available in, e.g. to host multiple applications side-by-side, in different directories, under the same domain name.
+
+You can change the attribute through one of the following means, in order of recommendation:
+
+ * In the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`), find the line with the `session.cookie_path` directive and change its value as desired, e.g.:
+
+   ```
+   session.cookie_path = /
+   ```
+
+ * As early as possible in your application, and before you create the `Auth` instance, call `\ini_set` to change the value of the `session.cookie_path` directive as desired, e.g.:
+
+   ```php
+   \ini_set('session.cookie_path', '/');
+   ```
+
+   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`).
+
+#### Controlling client-side script access to cookies
+
+Using the `httponly` attribute, you can control whether client-side scripts, i.e. JavaScript, should be able to access your cookies or not. For security reasons, it is best to *deny* script access to your cookies, which reduces the damage that successful XSS attacks against your application could do, for example.
+
+Thus, you should always set `httponly` to `1`, except for the rare cases where you really need access to your cookies from JavaScript and can’t find any better solution. In those cases, set the attribute to `0`, but be aware of the consequences.
+
+You can change the attribute through one of the following means, in order of recommendation:
+
+ * In the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`), find the line with the `session.cookie_httponly` directive and change its value as desired, e.g.:
+
+   ```
+   session.cookie_httponly = 1
+   ```
+
+ * As early as possible in your application, and before you create the `Auth` instance, call `\ini_set` to change the value of the `session.cookie_httponly` directive as desired, e.g.:
+
+   ```php
+   \ini_set('session.cookie_httponly', 1);
+   ```
+
+   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`).
+
+#### Configuring transport security for cookies
+
+Using the `secure` attribute, you can control whether cookies should be sent over *any* connection, including plain HTTP, or whether a secure connection, i.e. HTTPS (with SSL/TLS), should be required. The former (less secure) mode can be chosen by setting the attribute to `0`, and the latter (more secure) mode can be chosen by setting the attribute to `1`.
+
+Obviously, this solely depends on whether you are able to serve *all* pages exclusively via HTTPS. If you can, you should set the attribute to `1` and possibly combine it with HTTP redirects to the secure protocol and HTTP Strict Transport Security (HSTS). Otherwise, you may have to keep the attribute set to `0`.
+
+You can change the attribute through one of the following means, in order of recommendation:
+
+ * In the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`), find the line with the `session.cookie_secure` directive and change its value as desired, e.g.:
+
+   ```
+   session.cookie_secure = 1
+   ```
+
+ * As early as possible in your application, and before you create the `Auth` instance, call `\ini_set` to change the value of the `session.cookie_secure` directive as desired, e.g.:
+
+   ```php
+   \ini_set('session.cookie_secure', 1);
+   ```
+
+   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`).
+
 ### Utilities

 #### Creating a random string
@@ -914,11 +1206,11 @@ For detailed information on how to read and write session data conveniently, ple

 ### What about password hashing?

-Any password or authentication token is automatically hashed using the ["bcrypt"](https://en.wikipedia.org/wiki/Bcrypt) function, which is based on the ["Blowfish" cipher](https://en.wikipedia.org/wiki/Blowfish_(cipher)) and (still) considered one of the strongest password hash functions today. "bcrypt" is used with 1,024 iterations, i.e. a "cost" factor of 10. A random ["salt"](https://en.wikipedia.org/wiki/Salt_(cryptography)) is applied automatically as well.
+Any password or authentication token is automatically hashed using the [“bcrypt”](https://en.wikipedia.org/wiki/Bcrypt) function, which is based on the [“Blowfish” cipher](https://en.wikipedia.org/wiki/Blowfish_(cipher)) and (still) considered one of the strongest password hash functions today. “bcrypt” is used with 1,024 iterations, i.e. a “cost” factor of 10. A random [“salt”](https://en.wikipedia.org/wiki/Salt_(cryptography)) is applied automatically as well.

 You can verify this configuration by looking at the hashes in your database table `users`. If the above is true with your setup, all password hashes in your `users` table should start with the prefix `$2$10$`, `$2a$10$` or `$2y$10$`.

-When new algorithms (such as [Argon2](https://en.wikipedia.org/wiki/Argon2)) may be introduced in the future, this library will automatically take care of "upgrading" your existing password hashes whenever a user signs in or changes their password.
+When new algorithms (such as [Argon2](https://en.wikipedia.org/wiki/Argon2)) may be introduced in the future, this library will automatically take care of “upgrading” your existing password hashes whenever a user signs in or changes their password.

 ### How can I implement custom password requirements?

@@ -928,13 +1220,13 @@ To allow for maximum flexibility and ease of use, this library has been designed

 ```php
 function isPasswordAllowed($password) {
-    if (strlen($password) < 8) {
+    if (\strlen($password) < 8) {
        return false;
    }

    $blacklist = [ 'password1', '123456', 'qwerty' ];

-    if (in_array($password, $blacklist)) {
+    if (\in_array($password, $blacklist)) {
        return false;
    }

@@ -948,7 +1240,7 @@ if (isPasswordAllowed($password)) {

 ### Why are there problems when using other libraries that work with sessions?

-You might try loading this library first, and creating the `Auth` instance first, *before* loading the other libraries. Apart from that, there's probably not much we can do here.
+You might try loading this library first, and creating the `Auth` instance first, *before* loading the other libraries. Apart from that, there’s probably not much we can do here.

 ### Why are other sites not able to frame or embed my site?

@@ -969,11 +1261,11 @@ This library throws two types of exceptions to indicate problems:

 * Serve *all* pages over HTTPS only, i.e. using SSL/TLS for every single request.
 * You should enforce a minimum length for passwords, e.g. 10 characters, but *never* any maximum length, at least not anywhere below 100 characters. Moreover, you should *not* restrict the set of allowed characters.
- * Whenever a user was remembered through the "remember me" feature enabled or disabled during sign in, which means that they did not log in by typing their password, you should require re-authentication for critical features.
+ * Whenever a user was remembered through the “remember me” feature enabled or disabled during sign in, which means that they did not log in by typing their password, you should require re-authentication for critical features.
 * Encourage users to use pass*phrases*, i.e. combinations of words or even full sentences, instead of single pass*words*.
 * Do not prevent users' password managers from working correctly. Thus, use the standard form fields only and do not prevent copy and paste.
- * Before executing sensitive account operations (e.g. changing a user's email address, deleting a user's account), you should always require re-authentication, i.e. require the user to verify their login credentials once more.
- * You should not offer an online password reset feature ("forgot password") for high-security applications.
+ * Before executing sensitive account operations (e.g. changing a user’s email address, deleting a user’s account), you should always require re-authentication, i.e. require the user to verify their login credentials once more.
+ * You should not offer an online password reset feature (“forgot password”) for high-security applications.
 * For high-security applications, you should not use email addresses as identifiers. Instead, choose identifiers that are specific to the application and secret, e.g. an internal customer number.

 ## Contributing
--- a/composer.json
+++ b/composer.json
@@ -5,7 +5,7 @@
 		"php": ">=5.6.0",
 		"ext-openssl": "*",
 		"delight-im/base64": "^1.0",
-		"delight-im/cookie": "^2.1",
+		"delight-im/cookie": "^3.1",
 		"delight-im/db": "^1.2"
 	},
 	"type": "library",
--- 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": "8ab7c9ad8ef2bc7d9a6beb27f9bf4df5",
+    "content-hash": "54d541ae3c5ba25b0cc06688d2b65467",
    "packages": [
        {
            "name": "delight-im/base64",
@@ -49,16 +49,16 @@
        },
        {
            "name": "delight-im/cookie",
-            "version": "v2.1.3",
+            "version": "v3.1.0",
            "source": {
                "type": "git",
                "url": "https://github.com/delight-im/PHP-Cookie.git",
-                "reference": "a66c8a02aa4776c4b7d3d04c695411f73e04e1eb"
+                "reference": "76ef2a21817cf7a034f85fc3f4d4bfc60f873947"
            },
            "dist": {
                "type": "zip",
-                "url": "https://api.github.com/repos/delight-im/PHP-Cookie/zipball/a66c8a02aa4776c4b7d3d04c695411f73e04e1eb",
-                "reference": "a66c8a02aa4776c4b7d3d04c695411f73e04e1eb",
+                "url": "https://api.github.com/repos/delight-im/PHP-Cookie/zipball/76ef2a21817cf7a034f85fc3f4d4bfc60f873947",
+                "reference": "76ef2a21817cf7a034f85fc3f4d4bfc60f873947",
                "shasum": ""
            },
            "require": {
@@ -86,7 +86,7 @@
                "samesite",
                "xss"
            ],
-            "time": "2017-07-26T14:03:38+00:00"
+            "time": "2017-10-18T19:48:59+00:00"
        },
        {
            "name": "delight-im/db",
--- a/src/Administration.php
+++ b/src/Administration.php
@@ -9,6 +9,7 @@
 namespace Delight\Auth;

 use Delight\Db\PdoDatabase;
+use Delight\Db\PdoDsn;
 use Delight\Db\Throwable\Error;

 require_once __DIR__ . '/Exceptions.php';
@@ -17,12 +18,10 @@ require_once __DIR__ . '/Exceptions.php';
 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
 	 */
-	public function __construct(PdoDatabase $databaseConnection, $dbTablePrefix = null) {
+	public function __construct($databaseConnection, $dbTablePrefix = null) {
 		parent::__construct($databaseConnection, $dbTablePrefix);
 	}

@@ -107,7 +106,7 @@ final class Administration extends UserManager {
 	 */
 	public function deleteUserByUsername($username) {
 		$userData = $this->getUserDataByUsername(
-			trim($username),
+			\trim($username),
 			[ 'id' ]
 		);

@@ -286,6 +285,133 @@ final class Administration extends UserManager {
 		return ($rolesBitmask & $role) === $role;
 	}

+	/**
+	 * Returns the roles of the user with the given ID, mapping the numerical values to their descriptive names
+	 *
+	 * @param int $userId the ID of the user to return the roles for
+	 * @return array
+	 * @throws UnknownIdException if no user with the specified ID has been found
+	 *
+	 * @see Role
+	 */
+	public function getRolesForUserById($userId) {
+		$userId = (int) $userId;
+
+		$rolesBitmask = $this->db->selectValue(
+			'SELECT roles_mask FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
+			[ $userId ]
+		);
+
+		if ($rolesBitmask === null) {
+			throw new UnknownIdException();
+		}
+
+		return \array_filter(
+			Role::getMap(),
+			function ($each) use ($rolesBitmask) {
+				return ($rolesBitmask & $each) === $each;
+			},
+			\ARRAY_FILTER_USE_KEY
+		);
+	}
+
+	/**
+	 * Signs in as the user with the specified ID
+	 *
+	 * @param int $id the ID of the user to sign in as
+	 * @throws UnknownIdException if no user with the specified ID has been found
+	 * @throws EmailNotVerifiedException if the user has not verified their email address via a confirmation method yet
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function logInAsUserById($id) {
+		$numberOfMatchedUsers = $this->logInAsUserByColumnValue('id', (int) $id);
+
+		if ($numberOfMatchedUsers === 0) {
+			throw new UnknownIdException();
+		}
+	}
+
+	/**
+	 * Signs in as the user with the specified email address
+	 *
+	 * @param string $email the email address of the user to sign in as
+	 * @throws InvalidEmailException if no user with the specified email address has been found
+	 * @throws EmailNotVerifiedException if the user has not verified their email address via a confirmation method yet
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function logInAsUserByEmail($email) {
+		$email = self::validateEmailAddress($email);
+
+		$numberOfMatchedUsers = $this->logInAsUserByColumnValue('email', $email);
+
+		if ($numberOfMatchedUsers === 0) {
+			throw new InvalidEmailException();
+		}
+	}
+
+	/**
+	 * Signs in as the user with the specified display name
+	 *
+	 * @param string $username the display name of the user to sign in as
+	 * @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 EmailNotVerifiedException if the user has not verified their email address via a confirmation method yet
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function logInAsUserByUsername($username) {
+		$numberOfMatchedUsers = $this->logInAsUserByColumnValue('username', \trim($username));
+
+		if ($numberOfMatchedUsers === 0) {
+			throw new UnknownUsernameException();
+		}
+		elseif ($numberOfMatchedUsers > 1) {
+			throw new AmbiguousUsernameException();
+		}
+	}
+
+	/**
+	 * 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
 	 *
@@ -306,7 +432,7 @@ final class Administration extends UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 	}

@@ -331,7 +457,7 @@ final class Administration extends UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

 		if ($userData === null) {
@@ -352,7 +478,7 @@ final class Administration extends UserManager {
 			return true;
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 	}

@@ -404,4 +530,42 @@ final class Administration extends UserManager {
 		);
 	}

+	/**
+	 * Signs in as the user for which the column with the specified name has the given value
+	 *
+	 * You must never pass untrusted input to the parameter that takes the column name
+	 *
+	 * @param string $columnName the name of the column to filter by
+	 * @param mixed $columnValue the value to look for in the selected column
+	 * @return int the number of matched users (where only a value of one means that the login may have been successful)
+	 * @throws EmailNotVerifiedException if the user has not verified their email address via a confirmation method yet
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	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',
+				[ $columnValue ]
+			);
+		}
+		catch (Error $e) {
+			throw new DatabaseError($e->getMessage());
+		}
+
+		$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'], \PHP_INT_MAX, false);
+			}
+			else {
+				throw new EmailNotVerifiedException();
+			}
+		}
+
+		return $numberOfMatchingUsers;
+	}
+
 }
--- a/src/Auth.php
+++ b/src/Auth.php
--- a/src/Role.php
+++ b/src/Role.php
@@ -32,14 +32,47 @@ final class Role {
 	const SUPER_EDITOR = 524288;
 	const SUPER_MODERATOR = 1048576;
 	const TRANSLATOR = 2097152;
-	// const XXX = 4194304;
-	// const XXX = 8388608;
-	// const XXX = 16777216;
-	// const XXX = 33554432;
-	// const XXX = 67108864;
-	// const XXX = 134217728;
-	// const XXX = 268435456;
-	// const XXX = 536870912;
+	// const XYZ = 4194304;
+	// const XYZ = 8388608;
+	// const XYZ = 16777216;
+	// const XYZ = 33554432;
+	// const XYZ = 67108864;
+	// const XYZ = 134217728;
+	// const XYZ = 268435456;
+	// const XYZ = 536870912;
+
+	/**
+	 * Returns an array mapping the numerical role values to their descriptive names
+	 *
+	 * @return array
+	 */
+	public static function getMap() {
+		$reflectionClass = new \ReflectionClass(static::class);
+
+		return \array_flip($reflectionClass->getConstants());
+	}
+
+	/**
+	 * Returns the descriptive role names
+	 *
+	 * @return string[]
+	 */
+	public static function getNames() {
+		$reflectionClass = new \ReflectionClass(static::class);
+
+		return \array_keys($reflectionClass->getConstants());
+	}
+
+	/**
+	 * Returns the numerical role values
+	 *
+	 * @return int[]
+	 */
+	public static function getValues() {
+		$reflectionClass = new \ReflectionClass(static::class);
+
+		return \array_values($reflectionClass->getConstants());
+	}

 	private function __construct() {}

--- a/src/UserManager.php
+++ b/src/UserManager.php
@@ -9,6 +9,7 @@
 namespace Delight\Auth;

 use Delight\Base64\Base64;
+use Delight\Cookie\Session;
 use Delight\Db\PdoDatabase;
 use Delight\Db\PdoDsn;
 use Delight\Db\Throwable\Error;
@@ -23,7 +24,24 @@ require_once __DIR__ . '/Exceptions.php';
 */
 abstract class UserManager {

-	const CONFIRMATION_REQUESTS_TTL_IN_SECONDS = 60 * 60 * 24;
+	/** @var string session field for whether the client is currently signed in */
+	const SESSION_FIELD_LOGGED_IN = 'auth_logged_in';
+	/** @var string session field for the ID of the user who is currently signed in (if any) */
+	const SESSION_FIELD_USER_ID = 'auth_user_id';
+	/** @var string session field for the email address of the user who is currently signed in (if any) */
+	const SESSION_FIELD_EMAIL = 'auth_email';
+	/** @var string session field for the display name (if any) of the user who is currently signed in (if any) */
+	const SESSION_FIELD_USERNAME = 'auth_username';
+	/** @var string session field for the status of the user who is currently signed in (if any) as one of the constants from the {@see Status} class */
+	const SESSION_FIELD_STATUS = 'auth_status';
+	/** @var string session field for the roles of the user who is currently signed in (if any) as a bitmask using constants from the {@see Role} class */
+	const SESSION_FIELD_ROLES = 'auth_roles';
+	/** @var string session field for whether the user who is currently signed in (if any) has been remembered (instead of them having authenticated actively) */
+	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;
@@ -40,10 +58,10 @@ abstract class UserManager {
 	 */
 	public static function createRandomString($maxLength = 24) {
 		// calculate how many bytes of randomness we need for the specified string length
-		$bytes = floor(intval($maxLength) / 4) * 3;
+		$bytes = \floor((int) $maxLength / 4) * 3;

 		// get random data
-		$data = openssl_random_pseudo_bytes($bytes);
+		$data = \openssl_random_pseudo_bytes($bytes);

 		// return the Base64-encoded result
 		return Base64::encodeUrlSafe($data);
@@ -103,12 +121,12 @@ abstract class UserManager {
 	 * @see confirmEmailAndSignIn
 	 */
 	protected function createUserInternal($requireUniqueUsername, $email, $password, $username = null, callable $callback = null) {
-		ignore_user_abort(true);
+		\ignore_user_abort(true);

 		$email = self::validateEmailAddress($email);
 		$password = self::validatePassword($password);

-		$username = isset($username) ? trim($username) : null;
+		$username = isset($username) ? \trim($username) : null;

 		// if the supplied username is the empty string or has consisted of whitespace only
 		if ($username === '') {
@@ -134,8 +152,8 @@ abstract class UserManager {
 			}
 		}

-		$password = password_hash($password, PASSWORD_DEFAULT);
-		$verified = isset($callback) && is_callable($callback) ? 0 : 1;
+		$password = \password_hash($password, \PASSWORD_DEFAULT);
+		$verified = \is_callable($callback) ? 0 : 1;

 		try {
 			$this->db->insert(
@@ -145,7 +163,7 @@ abstract class UserManager {
 					'password' => $password,
 					'username' => $username,
 					'verified' => $verified,
-					'registered' => time()
+					'registered' => \time()
 				]
 			);
 		}
@@ -154,7 +172,7 @@ abstract class UserManager {
 			throw new UserAlreadyExistsException();
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

 		$newUserId = (int) $this->db->getLastInsertId();
@@ -166,6 +184,63 @@ 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->dbTablePrefix . '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
+	 *
+	 * This may happen via the standard login, via the "remember me" feature, or due to impersonation by administrators
+	 *
+	 * @param int $userId the ID of the user
+	 * @param string $email the email address of the user
+	 * @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, $forceLogout, $remembered) {
+		// re-generate the session ID to prevent session fixation attacks (requests a cookie to be written on the client)
+		Session::regenerate(true);
+
+		// save the user data in the session variables maintained by this library
+		$_SESSION[self::SESSION_FIELD_LOGGED_IN] = true;
+		$_SESSION[self::SESSION_FIELD_USER_ID] = (int) $userId;
+		$_SESSION[self::SESSION_FIELD_EMAIL] = $email;
+		$_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();
+	}
+
 	/**
 	 * Returns the requested user data for the account with the specified username (if any)
 	 *
@@ -180,7 +255,7 @@ abstract class UserManager {
 	 */
 	protected function getUserDataByUsername($username, array $requestedColumns) {
 		try {
-			$projection = implode(', ', $requestedColumns);
+			$projection = \implode(', ', $requestedColumns);

 			$users = $this->db->select(
 				'SELECT ' . $projection . ' FROM ' . $this->dbTablePrefix . 'users WHERE username = ? LIMIT 2 OFFSET 0',
@@ -188,14 +263,14 @@ abstract class UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

 		if (empty($users)) {
 			throw new UnknownUsernameException();
 		}
 		else {
-			if (count($users) === 1) {
+			if (\count($users) === 1) {
 				return $users[0];
 			}
 			else {
@@ -216,9 +291,9 @@ abstract class UserManager {
 			throw new InvalidEmailException();
 		}

-		$email = trim($email);
+		$email = \trim($email);

-		if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
+		if (!\filter_var($email, \FILTER_VALIDATE_EMAIL)) {
 			throw new InvalidEmailException();
 		}

@@ -237,9 +312,9 @@ abstract class UserManager {
 			throw new InvalidPasswordException();
 		}

-		$password = trim($password);
+		$password = \trim($password);

-		if (strlen($password) < 1) {
+		if (\strlen($password) < 1) {
 			throw new InvalidPasswordException();
 		}

@@ -265,10 +340,8 @@ abstract class UserManager {
 	protected function createConfirmationRequest($userId, $email, callable $callback) {
 		$selector = self::createRandomString(16);
 		$token = self::createRandomString(16);
-		$tokenHashed = password_hash($token, PASSWORD_DEFAULT);
-
-		// the request shall be valid for one day
-		$expires = time() + self::CONFIRMATION_REQUESTS_TTL_IN_SECONDS;
+		$tokenHashed = \password_hash($token, \PASSWORD_DEFAULT);
+		$expires = \time() + 60 * 60 * 24;

 		try {
 			$this->db->insert(
@@ -283,10 +356,10 @@ abstract class UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}

-		if (isset($callback) && is_callable($callback)) {
+		if (\is_callable($callback)) {
 			$callback($selector, $token);
 		}
 		else {
@@ -294,4 +367,45 @@ 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->dbTablePrefix . '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->dbTablePrefix . 'users SET force_logout = force_logout + 1 WHERE id = ?',
+			[ $userId ]
+		);
+	}
+
 }
--- a/tests/index.php
+++ b/tests/index.php
@@ -15,33 +15,36 @@
 */

 // enable error reporting
-error_reporting(E_ALL);
-ini_set('display_errors', 'stdout');
+\error_reporting(\E_ALL);
+\ini_set('display_errors', 'stdout');

 // enable assertions
-ini_set('assert.active', 1);
-@ini_set('zend.assertions', 1);
-ini_set('assert.exception', 1);
+\ini_set('assert.active', 1);
+@\ini_set('zend.assertions', 1);
+\ini_set('assert.exception', 1);

-header('Content-type: text/html; charset=utf-8');
+\header('Content-type: text/html; charset=utf-8');

 require __DIR__.'/../vendor/autoload.php';

-$db = new PDO('mysql:dbname=php_auth;host=127.0.0.1;charset=utf8mb4', 'root', 'monkey');
+$db = new \PDO('mysql:dbname=php_auth;host=127.0.0.1;charset=utf8mb4', 'root', 'monkey');
 // or
-// $db = new PDO('sqlite:../Databases/php_auth.sqlite');
+// $db = new \PDO('pgsql:dbname=php_auth;host=127.0.0.1;port=5432', 'postgres', 'monkey');
+// or
+// $db = new \PDO('sqlite:../Databases/php_auth.sqlite');

 $auth = new \Delight\Auth\Auth($db);

-$result = processRequestData($auth);
+$result = \processRequestData($auth);

-showDebugData($auth, $result);
+\showGeneralForm();
+\showDebugData($auth, $result);

 if ($auth->check()) {
-	showAuthenticatedUserForm($auth);
+	\showAuthenticatedUserForm($auth);
 }
 else {
-	showGuestUserForm();
+	\showGuestUserForm();
 }

 function processRequestData(\Delight\Auth\Auth $auth) {
@@ -83,7 +86,7 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					return 'wrong password';
 				}
 				catch (\Delight\Auth\EmailNotVerifiedException $e) {
-					return 'email not verified';
+					return 'email address not verified';
 				}
 				catch (\Delight\Auth\TooManyRequestsException $e) {
 					return 'too many requests';
@@ -98,11 +101,11 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 							echo "\n";
 							echo '  >  Selector';
 							echo "\t\t\t\t";
-							echo htmlspecialchars($selector);
+							echo \htmlspecialchars($selector);
 							echo "\n";
 							echo '  >  Token';
 							echo "\t\t\t\t";
-							echo htmlspecialchars($token);
+							echo \htmlspecialchars($token);
 							echo '</pre>';
 						};
 					}
@@ -148,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';
@@ -177,11 +179,11 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 						echo "\n";
 						echo '  >  Selector';
 						echo "\t\t\t\t";
-						echo htmlspecialchars($selector);
+						echo \htmlspecialchars($selector);
 						echo "\n";
 						echo '  >  Token';
 						echo "\t\t\t\t";
-						echo htmlspecialchars($token);
+						echo \htmlspecialchars($token);
 						echo '</pre>';
 					});

@@ -202,11 +204,11 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 						echo "\n";
 						echo '  >  Selector';
 						echo "\t\t\t\t";
-						echo htmlspecialchars($selector);
+						echo \htmlspecialchars($selector);
 						echo "\n";
 						echo '  >  Token';
 						echo "\t\t\t\t";
-						echo htmlspecialchars($token);
+						echo \htmlspecialchars($token);
 						echo '</pre>';
 					});

@@ -227,11 +229,11 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 						echo "\n";
 						echo '  >  Selector';
 						echo "\t\t\t\t";
-						echo htmlspecialchars($selector);
+						echo \htmlspecialchars($selector);
 						echo "\n";
 						echo '  >  Token';
 						echo "\t\t\t\t";
-						echo htmlspecialchars($token);
+						echo \htmlspecialchars($token);
 						echo '</pre>';
 					});

@@ -241,10 +243,10 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					return 'invalid email address';
 				}
 				catch (\Delight\Auth\EmailNotVerifiedException $e) {
-					return 'email not verified';
+					return 'email address not verified';
 				}
 				catch (\Delight\Auth\ResetDisabledException $e) {
-					return 'password reset disabled';
+					return 'password reset is disabled';
 				}
 				catch (\Delight\Auth\TooManyRequestsException $e) {
 					return 'too many requests';
@@ -263,7 +265,7 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					return 'token expired';
 				}
 				catch (\Delight\Auth\ResetDisabledException $e) {
-					return 'password reset disabled';
+					return 'password reset is disabled';
 				}
 				catch (\Delight\Auth\InvalidPasswordException $e) {
 					return 'invalid password';
@@ -272,6 +274,25 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					return 'too many requests';
 				}
 			}
+			else if ($_POST['action'] === 'canResetPassword') {
+				try {
+					$auth->canResetPasswordOrThrow($_POST['selector'], $_POST['token']);
+
+					return 'yes';
+				}
+				catch (\Delight\Auth\InvalidSelectorTokenPairException $e) {
+					return 'invalid token';
+				}
+				catch (\Delight\Auth\TokenExpiredException $e) {
+					return 'token expired';
+				}
+				catch (\Delight\Auth\ResetDisabledException $e) {
+					return 'password reset is disabled';
+				}
+				catch (\Delight\Auth\TooManyRequestsException $e) {
+					return 'too many requests';
+				}
+			}
 			else if ($_POST['action'] === 'reconfirmPassword') {
 				try {
 					return $auth->reconfirmPassword($_POST['password']) ? 'correct' : 'wrong';
@@ -320,11 +341,11 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 						echo "\n";
 						echo '  >  Selector';
 						echo "\t\t\t\t";
-						echo htmlspecialchars($selector);
+						echo \htmlspecialchars($selector);
 						echo "\n";
 						echo '  >  Token';
 						echo "\t\t\t\t";
-						echo htmlspecialchars($token);
+						echo \htmlspecialchars($token);
 						echo '</pre>';
 					});

@@ -356,8 +377,33 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					return 'not logged in';
 				}
 			}
-			else if ($_POST['action'] === 'logout') {
-				$auth->logout();
+			else if ($_POST['action'] === 'logOut') {
+				$auth->logOut();
+
+				return 'ok';
+			}
+			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';
 			}
@@ -416,7 +462,7 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					}
 				}
 				else {
-					return 'either ID, email or username required';
+					return 'either ID, email address or username required';
 				}

 				return 'ok';
@@ -451,7 +497,7 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 						}
 					}
 					else {
-						return 'either ID, email or username required';
+						return 'either ID, email address or username required';
 					}
 				}
 				else {
@@ -490,7 +536,7 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 						}
 					}
 					else {
-						return 'either ID, email or username required';
+						return 'either ID, email address or username required';
 					}
 				}
 				else {
@@ -517,8 +563,115 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					return 'ID required';
 				}
 			}
+			else if ($_POST['action'] === 'admin.getRoles') {
+				if (isset($_POST['id'])) {
+					try {
+						return $auth->admin()->getRolesForUserById($_POST['id']);
+					}
+					catch (\Delight\Auth\UnknownIdException $e) {
+						return 'unknown ID';
+					}
+				}
+				else {
+					return 'ID required';
+				}
+			}
+			else if ($_POST['action'] === 'admin.logInAsUserById') {
+				if (isset($_POST['id'])) {
+					try {
+						$auth->admin()->logInAsUserById($_POST['id']);
+
+						return 'ok';
+					}
+					catch (\Delight\Auth\UnknownIdException $e) {
+						return 'unknown ID';
+					}
+					catch (\Delight\Auth\EmailNotVerifiedException $e) {
+						return 'email address not verified';
+					}
+				}
+				else {
+					return 'ID required';
+				}
+			}
+			else if ($_POST['action'] === 'admin.logInAsUserByEmail') {
+				if (isset($_POST['email'])) {
+					try {
+						$auth->admin()->logInAsUserByEmail($_POST['email']);
+
+						return 'ok';
+					}
+					catch (\Delight\Auth\InvalidEmailException $e) {
+						return 'unknown email address';
+					}
+					catch (\Delight\Auth\EmailNotVerifiedException $e) {
+						return 'email address not verified';
+					}
+				}
+				else {
+					return 'Email address required';
+				}
+			}
+			else if ($_POST['action'] === 'admin.logInAsUserByUsername') {
+				if (isset($_POST['username'])) {
+					try {
+						$auth->admin()->logInAsUserByUsername($_POST['username']);
+
+						return 'ok';
+					}
+					catch (\Delight\Auth\UnknownUsernameException $e) {
+						return 'unknown username';
+					}
+					catch (\Delight\Auth\AmbiguousUsernameException $e) {
+						return 'ambiguous username';
+					}
+					catch (\Delight\Auth\EmailNotVerifiedException $e) {
+						return 'email address not verified';
+					}
+				}
+				else {
+					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']);
+				throw new Exception('Unexpected action: ' . $_POST['action']);
 			}
 		}
 	}
@@ -529,57 +682,68 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 function showDebugData(\Delight\Auth\Auth $auth, $result) {
 	echo '<pre>';

-	echo 'Last operation'."\t\t\t\t";
-	var_dump($result);
-	echo 'Session ID'."\t\t\t\t";
-	var_dump(session_id());
+	echo 'Last operation' . "\t\t\t\t";
+	\var_dump($result);
+	echo 'Session ID' . "\t\t\t\t";
+	\var_dump(\session_id());
 	echo "\n";

-	echo '$auth->isLoggedIn()'."\t\t\t";
-	var_dump($auth->isLoggedIn());
-	echo '$auth->check()'."\t\t\t\t";
-	var_dump($auth->check());
+	echo '$auth->isLoggedIn()' . "\t\t\t";
+	\var_dump($auth->isLoggedIn());
+	echo '$auth->check()' . "\t\t\t\t";
+	\var_dump($auth->check());
 	echo "\n";

-	echo '$auth->getUserId()'."\t\t\t";
-	var_dump($auth->getUserId());
-	echo '$auth->id()'."\t\t\t\t";
-	var_dump($auth->id());
+	echo '$auth->getUserId()' . "\t\t\t";
+	\var_dump($auth->getUserId());
+	echo '$auth->id()' . "\t\t\t\t";
+	\var_dump($auth->id());
 	echo "\n";

-	echo '$auth->getEmail()'."\t\t\t";
-	var_dump($auth->getEmail());
-	echo '$auth->getUsername()'."\t\t\t";
-	var_dump($auth->getUsername());
+	echo '$auth->getEmail()' . "\t\t\t";
+	\var_dump($auth->getEmail());
+	echo '$auth->getUsername()' . "\t\t\t";
+	\var_dump($auth->getUsername());

-	echo '$auth->getStatus()'."\t\t\t";
-	echo convertStatusToText($auth);
+	echo '$auth->getStatus()' . "\t\t\t";
+	echo \convertStatusToText($auth);
 	echo ' / ';
-	var_dump($auth->getStatus());
+	\var_dump($auth->getStatus());

 	echo "\n";

-	echo 'Roles (super moderator)'."\t\t\t";
-	var_dump($auth->hasRole(\Delight\Auth\Role::SUPER_MODERATOR));
+	echo 'Roles (super moderator)' . "\t\t\t";
+	\var_dump($auth->hasRole(\Delight\Auth\Role::SUPER_MODERATOR));

-	echo 'Roles (developer *or* manager)'."\t\t";
-	var_dump($auth->hasAnyRole(\Delight\Auth\Role::DEVELOPER, \Delight\Auth\Role::MANAGER));
+	echo 'Roles (developer *or* manager)' . "\t\t";
+	\var_dump($auth->hasAnyRole(\Delight\Auth\Role::DEVELOPER, \Delight\Auth\Role::MANAGER));

-	echo 'Roles (developer *and* manager)'."\t\t";
-	var_dump($auth->hasAllRoles(\Delight\Auth\Role::DEVELOPER, \Delight\Auth\Role::MANAGER));
+	echo 'Roles (developer *and* manager)' . "\t\t";
+	\var_dump($auth->hasAllRoles(\Delight\Auth\Role::DEVELOPER, \Delight\Auth\Role::MANAGER));
+
+	echo 'Roles' . "\t\t\t\t\t";
+	echo \json_encode($auth->getRoles()) . "\n";

 	echo "\n";

-	echo '$auth->isRemembered()'."\t\t\t";
-	var_dump($auth->isRemembered());
-	echo '$auth->getIpAddress()'."\t\t\t";
-	var_dump($auth->getIpAddress());
+	echo '$auth->isRemembered()' . "\t\t\t";
+	\var_dump($auth->isRemembered());
+	echo '$auth->getIpAddress()' . "\t\t\t";
+	\var_dump($auth->getIpAddress());
 	echo "\n";

-	echo 'Auth::createRandomString()'."\t\t";
-	var_dump(\Delight\Auth\Auth::createRandomString());
-	echo 'Auth::createUuid()'."\t\t\t";
-	var_dump(\Delight\Auth\Auth::createUuid());
+	echo 'Session name' . "\t\t\t\t";
+	\var_dump(\session_name());
+	echo 'Auth::createRememberCookieName()' . "\t";
+	\var_dump(\Delight\Auth\Auth::createRememberCookieName());
+	echo "\n";
+
+	echo 'Auth::createCookieName(\'session\')' . "\t";
+	\var_dump(\Delight\Auth\Auth::createCookieName('session'));
+	echo 'Auth::createRandomString()' . "\t\t";
+	\var_dump(\Delight\Auth\Auth::createRandomString());
+	echo 'Auth::createUuid()' . "\t\t\t";
+	\var_dump(\Delight\Auth\Auth::createUuid());

 	echo '</pre>';
 }
@@ -621,8 +785,6 @@ function showGeneralForm() {
 }

 function showAuthenticatedUserForm(\Delight\Auth\Auth $auth) {
-	showGeneralForm();
-
 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="reconfirmPassword" />';
 	echo '<input type="text" name="password" placeholder="Password" /> ';
@@ -648,7 +810,7 @@ function showAuthenticatedUserForm(\Delight\Auth\Auth $auth) {
 	echo '<button type="submit">Change email address</button>';
 	echo '</form>';

-	showConfirmEmailForm();
+	\showConfirmEmailForm();

 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="setPasswordResetEnabled" />';
@@ -660,19 +822,29 @@ function showAuthenticatedUserForm(\Delight\Auth\Auth $auth) {
 	echo '</form>';

 	echo '<form action="" method="post" accept-charset="utf-8">';
-	echo '<input type="hidden" name="action" value="logout" />';
-	echo '<button type="submit">Logout</button>';
+	echo '<input type="hidden" name="action" value="logOut" />';
+	echo '<button type="submit">Log out</button>';
 	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	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() {
-	showGeneralForm();
-
 	echo '<h1>Public</h1>';

 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="login" />';
-	echo '<input type="text" name="email" placeholder="Email" /> ';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
 	echo '<input type="text" name="password" placeholder="Password" /> ';
 	echo '<select name="remember" size="1">';
 	echo '<option value="0">Remember (keep logged in)? — No</option>';
@@ -694,7 +866,7 @@ function showGuestUserForm() {

 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="register" />';
-	echo '<input type="text" name="email" placeholder="Email" /> ';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
 	echo '<input type="text" name="password" placeholder="Password" /> ';
 	echo '<input type="text" name="username" placeholder="Username (optional)" /> ';
 	echo '<select name="require_verification" size="1">';
@@ -708,11 +880,11 @@ function showGuestUserForm() {
 	echo '<button type="submit">Register</button>';
 	echo '</form>';

-	showConfirmEmailForm();
+	\showConfirmEmailForm();

 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="forgotPassword" />';
-	echo '<input type="text" name="email" placeholder="Email" /> ';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
 	echo '<button type="submit">Forgot password</button>';
 	echo '</form>';

@@ -724,11 +896,20 @@ function showGuestUserForm() {
 	echo '<button type="submit">Reset password</button>';
 	echo '</form>';

+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="canResetPassword" />';
+	echo '<input type="text" name="selector" placeholder="Selector" /> ';
+	echo '<input type="text" name="token" placeholder="Token" /> ';
+	echo '<button type="submit">Can reset password?</button>';
+	echo '</form>';
+
+	\showDestroySessionForm();
+
 	echo '<h1>Administration</h1>';

 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="admin.createUser" />';
-	echo '<input type="text" name="email" placeholder="Email" /> ';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
 	echo '<input type="text" name="password" placeholder="Password" /> ';
 	echo '<input type="text" name="username" placeholder="Username (optional)" /> ';
 	echo '<select name="require_unique_username" size="1">';
@@ -746,7 +927,7 @@ function showGuestUserForm() {

 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="admin.deleteUser" />';
-	echo '<input type="text" name="email" placeholder="Email" /> ';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
 	echo '<button type="submit">Delete user by email</button>';
 	echo '</form>';

@@ -759,51 +940,89 @@ function showGuestUserForm() {
 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="admin.addRole" />';
 	echo '<input type="text" name="id" placeholder="ID" /> ';
-	echo '<select name="role">' . createRolesOptions() . '</select>';
+	echo '<select name="role">' . \createRolesOptions() . '</select>';
 	echo '<button type="submit">Add role for user by ID</button>';
 	echo '</form>';

 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="admin.addRole" />';
-	echo '<input type="text" name="email" placeholder="Email" /> ';
-	echo '<select name="role">' . createRolesOptions() . '</select>';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
+	echo '<select name="role">' . \createRolesOptions() . '</select>';
 	echo '<button type="submit">Add role for user by email</button>';
 	echo '</form>';

 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="admin.addRole" />';
 	echo '<input type="text" name="username" placeholder="Username" /> ';
-	echo '<select name="role">' . createRolesOptions() . '</select>';
+	echo '<select name="role">' . \createRolesOptions() . '</select>';
 	echo '<button type="submit">Add role for user by username</button>';
 	echo '</form>';

 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="admin.removeRole" />';
 	echo '<input type="text" name="id" placeholder="ID" /> ';
-	echo '<select name="role">' . createRolesOptions() . '</select>';
+	echo '<select name="role">' . \createRolesOptions() . '</select>';
 	echo '<button type="submit">Remove role for user by ID</button>';
 	echo '</form>';

 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="admin.removeRole" />';
-	echo '<input type="text" name="email" placeholder="Email" /> ';
-	echo '<select name="role">' . createRolesOptions() . '</select>';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
+	echo '<select name="role">' . \createRolesOptions() . '</select>';
 	echo '<button type="submit">Remove role for user by email</button>';
 	echo '</form>';

 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="admin.removeRole" />';
 	echo '<input type="text" name="username" placeholder="Username" /> ';
-	echo '<select name="role">' . createRolesOptions() . '</select>';
+	echo '<select name="role">' . \createRolesOptions() . '</select>';
 	echo '<button type="submit">Remove role for user by username</button>';
 	echo '</form>';

 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="admin.hasRole" />';
 	echo '<input type="text" name="id" placeholder="ID" /> ';
-	echo '<select name="role">' . createRolesOptions() . '</select>';
+	echo '<select name="role">' . \createRolesOptions() . '</select>';
 	echo '<button type="submit">Does user have role?</button>';
 	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="admin.getRoles" />';
+	echo '<input type="text" name="id" placeholder="ID" /> ';
+	echo '<button type="submit">Get user\'s roles</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="admin.logInAsUserById" />';
+	echo '<input type="text" name="id" placeholder="ID" /> ';
+	echo '<button type="submit">Log in as user by ID</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="admin.logInAsUserByEmail" />';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
+	echo '<button type="submit">Log in as user by email address</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="admin.logInAsUserByUsername" />';
+	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() {
@@ -821,7 +1040,7 @@ function showConfirmEmailForm() {

 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="resendConfirmationForEmail" />';
-	echo '<input type="text" name="email" placeholder="Email" /> ';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
 	echo '<button type="submit">Re-send confirmation</button>';
 	echo '</form>';

@@ -832,12 +1051,17 @@ function showConfirmEmailForm() {
 	echo '</form>';
 }

-function createRolesOptions() {
-	$roleReflection = new ReflectionClass(\Delight\Auth\Role::class);
+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 = '';

-	foreach ($roleReflection->getConstants() as $roleName => $roleValue) {
+	foreach (\Delight\Auth\Role::getMap() as $roleValue => $roleName) {
 		$out .= '<option value="' . $roleValue . '">' . $roleName . '</option>';
 	}
Author	SHA1	Message	Date
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
Marco	e7e174b05d	Only configure and start session if not already started	2018-03-12 22:29:56 +01:00
Marco	8f35cc9965	Optimize spacing in PostgreSQL schema	2018-03-12 18:44:32 +01:00
Marco	142ccc362f	Shorten line of text in README for better overview	2018-03-12 02:18:44 +01:00
Marco	bce31f9cfc	Link to MariaDB schema separately from MySQL in README	2018-03-12 02:15:35 +01:00
Marco	3ddc7af1b4	Document support for PostgreSQL	2018-03-12 02:11:54 +01:00
Marco	62d9e44aa4	Add check constraints for unsigned integers in PostgreSQL schema	2018-03-12 01:51:33 +01:00
Marco	1121685cef	Improve database schema for PostgreSQL	2018-03-12 01:51:15 +01:00
Tiberiu Chibici	2f9bab4779	Add database schema for PostgreSQL	2018-03-12 00:32:53 +01:00
Marco	89e99d727d	Document resynchronization of session data with authoritative database	2018-03-10 20:54:24 +01:00
Marco	21341d3c18	Regularly resynchronize session data with authoritative source in DB	2018-03-10 20:53:13 +01:00
Marco	a1ae66374b	Improve documentation on password reset by dividing it into steps	2018-03-10 17:47:03 +01:00
Marco	477164e8ec	Rename identifiers in comments to prevent highlighting in IDE	2018-03-10 17:46:05 +01:00
Marco	9478a43e9b	Re-implement method 'canResetPassword' using 'canResetPasswordOrThrow'	2018-03-10 04:13:14 +01:00
Marco	1ba8e1ff21	Document method 'canResetPasswordOrThrow' from class 'Auth'	2018-03-10 04:10:22 +01:00
Marco	1657102f75	Add tests for method 'canResetPasswordOrThrow' from class 'Auth'	2018-03-10 04:06:45 +01:00
Marco	d246248ab5	Implement method 'canResetPasswordOrThrow' in class 'Auth'	2018-03-10 03:54:42 +01:00
Marco	94531f24d3	Improve language	2018-03-10 03:50:12 +01:00
Marco	2f29830ed9	Improve documentation to use more suitable data source for token	2018-03-10 03:47:55 +01:00
Marco	42a8c1616c	Document method 'getRolesForUserById' from class 'Administration'	2018-03-10 03:10:17 +01:00
Marco	a2be4c61ee	Add tests for method 'getRolesForUserById' from class 'Administration'	2018-03-10 03:05:41 +01:00
Marco	d9f9198b45	Implement method 'getRolesForUserById' in class 'Administration'	2018-03-10 03:03:57 +01:00
Marco	13b58abebc	Document method 'getRoles' from class 'Auth'	2018-03-10 03:01:23 +01:00
Marco	b0bf7647ce	Add tests for method 'getRoles' from class 'Auth'	2018-03-10 02:56:32 +01:00
Marco	012577227a	Implement method 'getRoles' in class 'Auth'	2018-03-10 02:54:57 +01:00
Marco	d834623954	Document methods 'getMap', 'getNames' and 'getValues' of class 'Role'	2018-03-10 02:51:27 +01:00
Marco	d3594898cc	Make use of new method 'getMap' from class 'Role' in 'tests'	2018-03-10 02:03:25 +01:00
Marco	7d44158c32	Implement methods 'getMap', 'getNames' and 'getValues' in class 'Role'	2018-03-10 01:58:54 +01:00
Marco	04edd9f88f	Simplify migration guide using that method names are case-insensitive	2018-03-09 15:22:55 +01:00
Marco	cd2ac47912	Simplify general notes for any update or upgrade in migration guide	2018-01-25 00:01:50 +01:00
Marco	7bcf201972	Improve documentation on default value for IP address in README	2017-11-08 21:34:50 +01:00
Marco	09247e7203	Provide possibility to disable throttling during development	2017-11-08 21:34:05 +01:00
Marco	ab1c54fae2	Optimize order of throttling in 'changeEmail' method from class 'Auth'	2017-11-08 20:40:37 +01:00
Marco	23acb66cc7	Reduce permitted frequency of requests to change one's email address	2017-11-08 20:38:16 +01:00
Marco	a7a9d45302	Drop constant 'CONFIRMATION_REQUESTS_TTL_IN_SECONDS' in 'UserManager'	2017-11-08 20:30:09 +01:00
Marco	ba4dc29ca5	Optimize order of throttling in 'resendConfirmationForColumnValue'	2017-11-08 20:23:34 +01:00
Marco	0a97f67515	Enforce limits for resending confirmations solely via throttling	2017-11-08 20:21:35 +01:00
Marco	7a94c6acef	Improve documentation in 'confirmEmail' method from 'Auth' class	2017-11-08 19:23:22 +01:00
Marco	dbbbf1b193	Remove superfluous comment in 'UserManager'	2017-11-08 19:18:14 +01:00
Marco	9637dfa60d	Improve language	2017-11-05 02:37:48 +01:00
Marco	aec738a9db	Document methods for impersonating users in class 'Administration'	2017-11-03 15:48:21 +01:00
Marco	382ee5bf93	Add tests for methods to impersonate users in class 'Administration'	2017-11-03 15:44:39 +01:00
Marco	47d1e303aa	Implement methods for impersonating users in class 'Administration'	2017-11-03 15:21:45 +01:00
Marco	67443c122a	Move core logic of 'onLoginSuccessful' from 'Auth' to 'UserManager'	2017-11-03 08:50:59 +01:00
Marco	24056e89a4	Move constants holding names of session fields to 'UserManager'	2017-11-03 08:49:10 +01:00
Marco	c06bc7da1a	Improve documentation for method 'onLoginSuccessful' in class 'Auth'	2017-11-03 08:38:17 +01:00
Marco	aedd2125fc	Document constants holding names of session fields	2017-11-03 08:36:03 +01:00
Marco	425cf9b6f6	Write to session fields directly instead of using accessor methods	2017-11-03 08:33:41 +01:00
Marco	739fa7d574	Fix internal links in migration guide that should point to README	2017-10-21 23:15:15 +02:00
Marco	302feb5da2	Document 'secure' cookie attribute and how to change it in README	2017-10-21 22:32:01 +02:00
Marco	2ded232d8e	Document 'httponly' cookie attribute and how to change it in README	2017-10-21 22:30:41 +02:00
Marco	70a905afd7	Document 'path' cookie attribute and how to change it in README	2017-10-21 22:29:19 +02:00
Marco	84f3ad10a9	Document 'domain' cookie attribute and how to change it in README	2017-10-21 22:26:25 +02:00
Marco	81091df66b	Drop constructor arguments 'useHttps' and 'allowCookiesScriptAccess'	2017-10-20 23:07:36 +02:00
Marco	8926e7e708	Improve general upgrade guide in migration notes	2017-10-20 22:46:01 +02:00
Marco	eec450677f	Do not duplicate and overwrite parts of cookie configuration anymore Previously, PHP's configuration directives 'session.cookie_httponly' and 'session.cookie_secure' were always overwritten with duplicated and separately tracked variants of each directive	2017-10-20 22:30:16 +02:00
Marco	f1360dceba	Improve code style	2017-10-20 08:53:02 +02:00
Marco	2cf7b27ba3	Support empty path scope for cookies to restrict to current directory	2017-10-20 08:47:56 +02:00
Marco	ecd8015acf	Explain changes to domain scope of cookies in migration guide	2017-10-20 08:01:00 +02:00
Marco	1eedfd0e02	Simplify code based on assumptions about new 'Delight\Cookie' behavior	2017-10-20 01:12:04 +02:00
Marco	757579523c	Use constants from 'Delight\Cookie\Cookie' class for cookie prefixes	2017-10-19 22:33:18 +02:00
Marco	d695328a5a	Update dependencies	2017-10-19 22:29:50 +02:00
Marco	71506eaa05	Rename two methods for logout to highlight the better default version	2017-10-19 20:25:11 +02:00
Marco	ce8dbbc436	Delete 'remember me' cookies from previous major versions as well	2017-10-19 20:19:19 +02:00
Marco	d181219e40	Add documentation about cookies and their usage to README	2017-10-19 20:11:28 +02:00
Marco	891cef2511	Do not make repeated attempts to use invalid 'remember me' cookies	2017-10-19 03:00:28 +02:00
Marco	f70613b2b8	Ignore defined but empty selectors and tokens from 'remember me'	2017-10-19 02:55:49 +02:00
Marco	59816d1a40	Re-use 'remember me' cookie from previous major versions if available	2017-10-19 02:50:24 +02:00
Marco	1284f64f04	Fix documentation for method 'setRememberCookie' in class 'Auth'	2017-10-19 02:27:42 +02:00
Marco	8165e8917b	Change name of 'remember me' cookie to be dependent on session name	2017-10-19 01:44:19 +02:00
Marco	a4b68167a1	Prepare migration guide for next major release	2017-10-19 00:47:47 +02:00
Marco	fc2fb4bb44	Move 'Refresh' button from bottom to top in 'tests'	2017-10-19 00:36:08 +02:00
Marco	b2a3fde696	Add tests for method 'createRememberCookieName' from class 'Auth'	2017-10-18 23:08:01 +02:00
Marco	36880b87c9	Implement method 'createRememberCookieName' in class 'Auth'	2017-10-18 23:03:41 +02:00
Marco	4a66965994	Add tests for method 'createCookieName' from class 'Auth'	2017-10-18 23:01:15 +02:00
Marco	e7b590dc80	Implement method 'createCookieName' in class 'Auth'	2017-10-18 22:52:00 +02:00
Marco	33d2384c93	Add list of available cookie prefixes as constant in class 'Auth'	2017-10-18 22:48:14 +02:00
Marco	1169856217	Improve code style	2017-10-18 22:47:24 +02:00
Marco	fa75811679	Display current session name in 'tests'	2017-10-18 22:30:06 +02:00
Marco	fa8fa4887e	Improve documentation in class 'Auth'	2017-10-18 21:59:25 +02:00
Marco	8fecb86f15	Improve code style	2017-10-12 02:42:40 +02:00
Pavel Levin	04c466b309	Drop superfluous check using 'isset'	2017-10-12 02:32:13 +02:00
Marco	61041cc6fd	Invalidate outstanding password reset tokens on email address change	2017-09-27 21:58:28 +02:00
Marco	2ca835ac75	Improve language	2017-09-26 22:54:42 +02:00
Marco	1e23e6de13	Improve code style	2017-09-26 22:44:37 +02:00
Marco	50220d463b	Simplify documentation for 'changePasswordWithoutOldPassword'	2017-09-26 22:35:16 +02:00
Marco	f0bdd7b63e	Improve language	2017-09-26 22:28:00 +02:00
Marco	0473d59c39	Show that users are to reconfirm their password for reset control	2017-09-26 22:24:46 +02:00
Marco	f8f44a0286	Show that users are to reconfirm their password for email changes	2017-09-26 22:23:28 +02:00
Marco	ea91d8c92e	Explain that users should be notified about email address changes	2017-09-26 22:20:07 +02:00
Marco	7983bebd83	Explain that users should be informed via email about password changes	2017-09-26 22:17:21 +02:00
Marco	ddc5b50459	Improve list of methods that support 'remember me' feature in README	2017-09-23 00:17:31 +02:00
Marco	0b67f3d1e2	Document new method 'logOutButKeepSession' from class 'Auth'	2017-09-18 16:10:47 +02:00
Marco	16bcfa85ef	Add tests for new method 'logOutButKeepSession' in class 'Auth'	2017-09-18 16:10:19 +02:00
Marco	404739634d	Compose 'logout' using new 'logOutButKeepSession' and 'destroySession'	2017-09-18 16:08:32 +02:00
Marco	82a24fbbca	Implement method 'destroySession' in class 'Auth'	2017-09-18 16:07:05 +02:00
Marco	1a195adf39	Implement method 'logOutButKeepSession' in class 'Auth'	2017-09-18 16:01:47 +02:00
Marco	5e4d4fd072	Improve language	2017-09-18 15:53:59 +02:00
Marco	6162092618	Catch undefined IP address in rare use cases such as CLI usage	2017-09-18 14:54:39 +02:00
Marco	f142dd91dc	Emphasize primary line of project description in README	2017-08-25 07:57:47 +02:00