Fix internal links in migration guide that should point to README

Previously, PHP's configuration directives 'session.cookie_httponly'
and 'session.cookie_secure' were always overwritten with duplicated
and separately tracked variants of each directive

Migration.md

@@ -1,6 +1,7 @@
 # Migration
 
  * [General](#general)
+ * [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)
@@ -15,6 +16,62 @@ Update your version of this library via Composer [[?]](https://github.com/deligh
 $ composer update delight-im/auth
 ```
 
+If you want to perform a major version upgrade (e.g. from version `1.x.x` to version `2.x.x`), the version constraints defined in your `composer.json` [[?]](https://github.com/delight-im/Knowledge/blob/master/Composer%20(PHP).md) may not allow this. In that case, just add the dependency again to overwrite it with the latest version (or optionally with a specified version):
+
+```
+$ composer require delight-im/auth
+```
+
+## 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`. With both methods, mind the capitalization of the letter “O”.
+
+ * 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`
 
  * The database schema has changed.

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.
@@ -52,9 +52,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 +62,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 +79,12 @@ 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)
+ * [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,9 +93,9 @@ 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('sqlite:../Databases/my-database.sqlite');
 
 // or
 
@@ -102,13 +108,9 @@ $auth = new \Delight\Auth\Auth($db);
 
 If you have an open `PDO` connection already, just re-use it.
 
-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 `null`.
 
-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.
-
-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`.
-
-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.
+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.
 
 ### Registration (sign up)
 
@@ -134,17 +136,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 +170,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 +200,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 +221,9 @@ $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”)
 
 ```php
 try {
@@ -248,7 +250,7 @@ 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);
 ```
 
 As the next step, users will click on the link that they received. Extract the selector and token from the URL.
@@ -289,7 +291,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 +314,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 {
+    if ($auth->reconfirmPassword($_POST['password'])) {
         $auth->changeEmail($_POST['newEmail'], function ($selector, $token) {
-        // send `$selector` and `$token` to the user (e.g. via email)
+            // 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 +355,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,13 +401,15 @@ 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();
+// or
+$auth->logOutAndDestroySession();
 
 // user has been signed out
 ```
@@ -486,7 +485,7 @@ if ($auth->isSuspended()) {
 }
 ```
 
-#### Checking whether the user was "remembered"
+#### Checking whether the user was “remembered”
 
 ```php
 if ($auth->isRemembered()) {
@@ -507,13 +506,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 +529,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.
 
@@ -608,11 +607,11 @@ 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.
 
 #### 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 +693,21 @@ You may provide security-conscious (and experienced) users with the possibility
 
 ```php
 try {
+    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 +776,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 +898,138 @@ catch (\Delight\Auth\UnknownIdException $e) {
 }
 ```
 
+### 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 +1053,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 +1067,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 +1087,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 +1108,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

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",

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",

src/Administration.php

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

src/Auth.php

@@ -28,29 +28,24 @@ final class Auth extends UserManager {
 	const SESSION_FIELD_STATUS = 'auth_status';
 	const SESSION_FIELD_ROLES = 'auth_roles';
 	const SESSION_FIELD_REMEMBERED = 'auth_remembered';
+	const COOKIE_PREFIXES = [ Cookie::PREFIX_SECURE, Cookie::PREFIX_HOST ];
 	const COOKIE_CONTENT_SEPARATOR = '~';
-	const COOKIE_NAME_REMEMBER = 'auth_remember';
 
-	/** @var boolean whether HTTPS (TLS/SSL) will be used (recommended) */
-	private $useHttps;
-	/** @var boolean whether cookies should be accessible via client-side scripts (*not* recommended) */
-	private $allowCookiesScriptAccess;
 	/** @var string the user's current IP address */
 	private $ipAddress;
+	/** @var string the name of the cookie used for the 'remember me' feature */
+	private $rememberCookieName;
 
 	/**
 	 * @param PdoDatabase|PdoDsn|\PDO $databaseConnection the database connection to operate on
-	 * @param bool $useHttps whether HTTPS (TLS/SSL) will be used (recommended)
-	 * @param bool $allowCookiesScriptAccess whether cookies should be accessible via client-side scripts (*not* recommended)
 	 * @param string $ipAddress the IP address that should be used instead of the default setting (if any), e.g. when behind a proxy
 	 * @param string|null $dbTablePrefix (optional) the prefix for the names of all database tables used by this component
 	 */
-	public function __construct($databaseConnection, $useHttps = false, $allowCookiesScriptAccess = false, $ipAddress = null, $dbTablePrefix = null) {
+	public function __construct($databaseConnection, $ipAddress = null, $dbTablePrefix = null) {
 		parent::__construct($databaseConnection, $dbTablePrefix);
 
-		$this->useHttps = $useHttps;
-		$this->allowCookiesScriptAccess = $allowCookiesScriptAccess;
-		$this->ipAddress = empty($ipAddress) ? $_SERVER['REMOTE_ADDR'] : $ipAddress;
+		$this->ipAddress = !empty($ipAddress) ? $ipAddress : (isset($_SERVER['REMOTE_ADDR']) ? $_SERVER['REMOTE_ADDR'] : null);
+		$this->rememberCookieName = self::createRememberCookieName();
 
 		$this->initSession();
 		$this->enhanceHttpSecurity();
@@ -61,37 +56,32 @@ final class Auth extends UserManager {
 	/** Initializes the session and sets the correct configuration */
 	private function initSession() {
 		// use cookies to store session IDs
-		ini_set('session.use_cookies', 1);
+		\ini_set('session.use_cookies', 1);
 		// use cookies only (do not send session IDs in URLs)
-		ini_set('session.use_only_cookies', 1);
+		\ini_set('session.use_only_cookies', 1);
 		// do not send session IDs in URLs
-		ini_set('session.use_trans_sid', 0);
+		\ini_set('session.use_trans_sid', 0);
 
-		// get our cookie settings
-		$params = $this->createCookieSettings();
-		// define our new cookie settings
-		session_set_cookie_params($params['lifetime'], $params['path'], $params['domain'], $params['secure'], $params['httponly']);
-
-		// start the session
+		// start the session (requests a cookie to be written on the client)
 		@Session::start();
 	}
 
 	/** Improves the application's security over HTTP(S) by setting specific headers */
 	private function enhanceHttpSecurity() {
 		// remove exposure of PHP version (at least where possible)
-		header_remove('X-Powered-By');
+		\header_remove('X-Powered-By');
 
 		// if the user is signed in
 		if ($this->isLoggedIn()) {
 			// prevent clickjacking
-			header('X-Frame-Options: sameorigin');
+			\header('X-Frame-Options: sameorigin');
 			// prevent content sniffing (MIME sniffing)
-			header('X-Content-Type-Options: nosniff');
+			\header('X-Content-Type-Options: nosniff');
 
 			// disable caching of potentially sensitive data
-			header('Cache-Control: no-store, no-cache, must-revalidate', true);
-			header('Expires: Thu, 19 Nov 1981 00:00:00 GMT', true);
-			header('Pragma: no-cache', true);
+			\header('Cache-Control: no-store, no-cache, must-revalidate', true);
+			\header('Expires: Thu, 19 Nov 1981 00:00:00 GMT', true);
+			\header('Pragma: no-cache', true);
 		}
 	}
 
@@ -99,12 +89,25 @@ final class Auth extends UserManager {
 	private function processRememberDirective() {
 		// if the user is not signed in yet
 		if (!$this->isLoggedIn()) {
+			// if there is currently no cookie for the 'remember me' feature
+			if (!isset($_COOKIE[$this->rememberCookieName])) {
+				// if an old cookie for that feature from versions v1.x.x to v6.x.x has been found
+				if (isset($_COOKIE['auth_remember'])) {
+					// use the value from that old cookie instead
+					$_COOKIE[$this->rememberCookieName] = $_COOKIE['auth_remember'];
+				}
+			}
+
 			// if a remember cookie is set
-			if (isset($_COOKIE[self::COOKIE_NAME_REMEMBER])) {
+			if (isset($_COOKIE[$this->rememberCookieName])) {
+				// assume the cookie and its contents to be invalid until proven otherwise
+				$valid = false;
+
 				// split the cookie's content into selector and token
-				$parts = explode(self::COOKIE_CONTENT_SEPARATOR, $_COOKIE[self::COOKIE_NAME_REMEMBER], 2);
+				$parts = \explode(self::COOKIE_CONTENT_SEPARATOR, $_COOKIE[$this->rememberCookieName], 2);
+
 				// if both selector and token were found
-				if (isset($parts[0]) && isset($parts[1])) {
+				if (!empty($parts[0]) && !empty($parts[1])) {
 					try {
 						$rememberData = $this->db->selectRow(
 							'SELECT a.user, a.token, a.expires, b.email, b.username, b.status, b.roles_mask FROM ' . $this->dbTablePrefix . 'users_remembered AS a JOIN ' . $this->dbTablePrefix . 'users AS b ON a.user = b.id WHERE a.selector = ?',
@@ -116,13 +119,22 @@ final class Auth extends UserManager {
 					}
 
 					if (!empty($rememberData)) {
-						if ($rememberData['expires'] >= time()) {
-							if (password_verify($parts[1], $rememberData['token'])) {
+						if ($rememberData['expires'] >= \time()) {
+							if (\password_verify($parts[1], $rememberData['token'])) {
+								// the cookie and its contents have now been proven to be valid
+								$valid = true;
+
 								$this->onLoginSuccessful($rememberData['user'], $rememberData['email'], $rememberData['username'], $rememberData['status'], $rememberData['roles_mask'], true);
 							}
 						}
 					}
 				}
+
+				// if the cookie or its contents have been invalid
+				if (!$valid) {
+					// mark the cookie as such to prevent any further futile attempts
+					$this->setRememberCookie('', '', \time() + 60 * 60 * 24 * 365.25);
+				}
 			}
 		}
 	}
@@ -309,6 +321,48 @@ final class Auth extends UserManager {
 		}
 	}
 
+	/**
+	 * Logs the user out
+	 *
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function logOut() {
+		// if the user has been signed in
+		if ($this->isLoggedIn()) {
+			// get the user's ID
+			$userId = $this->getUserId();
+
+			// if a user ID was set
+			if (isset($userId)) {
+				// delete any existing remember directives
+				$this->deleteRememberDirective($userId);
+			}
+
+			// remove all session variables maintained by this library
+			unset($_SESSION[self::SESSION_FIELD_LOGGED_IN]);
+			unset($_SESSION[self::SESSION_FIELD_USER_ID]);
+			unset($_SESSION[self::SESSION_FIELD_EMAIL]);
+			unset($_SESSION[self::SESSION_FIELD_USERNAME]);
+			unset($_SESSION[self::SESSION_FIELD_STATUS]);
+			unset($_SESSION[self::SESSION_FIELD_ROLES]);
+			unset($_SESSION[self::SESSION_FIELD_REMEMBERED]);
+		}
+	}
+
+	/**
+	 * Destroys all session data
+	 *
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function destroySession() {
+		// remove all session variables without exception
+		$_SESSION = [];
+		// delete the session cookie
+		$this->deleteSessionCookie();
+		// let PHP destroy the session
+		\session_destroy();
+	}
+
 	/**
 	 * Creates a new directive keeping the user logged in ("remember me")
 	 *
@@ -319,8 +373,8 @@ final class Auth extends UserManager {
 	private function createRememberDirective($userId, $duration) {
 		$selector = self::createRandomString(24);
 		$token = self::createRandomString(32);
-		$tokenHashed = password_hash($token, PASSWORD_DEFAULT);
-		$expires = time() + ((int) $duration);
+		$tokenHashed = \password_hash($token, \PASSWORD_DEFAULT);
+		$expires = \time() + ((int) $duration);
 
 		try {
 			$this->db->insert(
@@ -357,20 +411,19 @@ final class Auth extends UserManager {
 			throw new DatabaseError();
 		}
 
-		$this->setRememberCookie(null, null, time() - 3600);
+		$this->setRememberCookie(null, null, \time() - 3600);
 	}
 
 	/**
 	 * Sets or updates the cookie that manages the "remember me" token
 	 *
-	 * @param string $selector the selector from the selector/token pair
-	 * @param string $token the token from the selector/token pair
-	 * @param int $expires the interval in seconds after which the token should expire
+	 * @param string|null $selector the selector from the selector/token pair
+	 * @param string|null $token the token from the selector/token pair
+	 * @param int $expires the UNIX time in seconds which the token should expire at
 	 * @throws AuthError if an internal problem occurred (do *not* catch)
 	 */
 	private function setRememberCookie($selector, $token, $expires) {
-		// get our cookie settings
-		$params = $this->createCookieSettings();
+		$params = \session_get_cookie_params();
 
 		if (isset($selector) && isset($token)) {
 			$content = $selector . self::COOKIE_CONTENT_SEPARATOR . $token;
@@ -379,29 +432,30 @@ final class Auth extends UserManager {
 			$content = '';
 		}
 
-		// set the cookie with the selector and token
-
-		$cookie = new Cookie(self::COOKIE_NAME_REMEMBER);
-
+		// save the cookie with the selector and token (requests a cookie to be written on the client)
+		$cookie = new Cookie($this->rememberCookieName);
 		$cookie->setValue($content);
 		$cookie->setExpiryTime($expires);
-
-		if (!empty($params['path'])) {
 		$cookie->setPath($params['path']);
-		}
-
-		if (!empty($params['domain'])) {
 		$cookie->setDomain($params['domain']);
-		}
-
 		$cookie->setHttpOnly($params['httponly']);
 		$cookie->setSecureOnly($params['secure']);
-
 		$result = $cookie->save();
 
 		if ($result === false) {
 			throw new HeadersAlreadySentError();
 		}
+
+		// if we've been deleting the cookie above
+		if (!isset($selector) || !isset($token)) {
+			// attempt to delete a potential old cookie from versions v1.x.x to v6.x.x as well (requests a cookie to be written on the client)
+			$cookie = new Cookie('auth_remember');
+			$cookie->setPath((!empty($params['path'])) ? $params['path'] : '/');
+			$cookie->setDomain($params['domain']);
+			$cookie->setHttpOnly($params['httponly']);
+			$cookie->setSecureOnly($params['secure']);
+			$cookie->delete();
+		}
 	}
 
 	/**
@@ -419,7 +473,7 @@ final class Auth extends UserManager {
 		try {
 			$this->db->update(
 				$this->dbTablePrefix . 'users',
-				[ 'last_login' => time() ],
+				[ 'last_login' => \time() ],
 				[ 'id' => $userId ]
 			);
 		}
@@ -427,7 +481,7 @@ final class Auth extends UserManager {
 			throw new DatabaseError();
 		}
 
-		// re-generate the session ID to prevent session fixation attacks
+		// 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
@@ -441,30 +495,13 @@ final class Auth extends UserManager {
 	}
 
 	/**
-	 * Logs out the user and destroys all session data
+	 * Logs the user out and destroys all session data
 	 *
 	 * @throws AuthError if an internal problem occurred (do *not* catch)
 	 */
-	public function logout() {
-		// if the user has been signed in
-		if ($this->isLoggedIn()) {
-			// get the user's ID
-			$userId = $this->getUserId();
-			// if a user ID was set
-			if (isset($userId)) {
-				// delete any existing remember directives
-				$this->deleteRememberDirective($userId);
-			}
-		}
-
-		// unset the session variables
-		$_SESSION = array();
-
-		// delete the cookie
-		$this->deleteSessionCookie();
-
-		// destroy the session
-		session_destroy();
+	public function logOutAndDestroySession() {
+		$this->logOut();
+		$this->destroySession();
 	}
 
 	/**
@@ -473,17 +510,12 @@ final class Auth extends UserManager {
 	 * @throws AuthError if an internal problem occurred (do *not* catch)
 	 */
 	private function deleteSessionCookie() {
-		// get our cookie settings
-		$params = $this->createCookieSettings();
+		$params = \session_get_cookie_params();
 
-		// cause the session cookie to be deleted
-		$cookie = new Cookie(session_name());
-		if (!empty($params['path'])) {
+		// ask for the session cookie to be deleted (requests a cookie to be written on the client)
+		$cookie = new Cookie(\session_name());
 		$cookie->setPath($params['path']);
-		}
-		if (!empty($params['domain'])) {
 		$cookie->setDomain($params['domain']);
-		}
 		$cookie->setHttpOnly($params['httponly']);
 		$cookie->setSecureOnly($params['secure']);
 		$result = $cookie->delete();
@@ -523,8 +555,20 @@ final class Auth extends UserManager {
 		}
 
 		if (!empty($confirmationData)) {
-			if (password_verify($token, $confirmationData['token'])) {
-				if ($confirmationData['expires'] >= time()) {
+			if (\password_verify($token, $confirmationData['token'])) {
+				if ($confirmationData['expires'] >= \time()) {
+					// invalidate any potential outstanding password reset requests
+					try {
+						$this->db->delete(
+							$this->dbTablePrefix . 'users_resets',
+							[ 'user' => $confirmationData['user_id'] ]
+						);
+					}
+					catch (Error $e) {
+						throw new DatabaseError();
+					}
+
+					// mark the email address as verified (and possibly update it to the new address given)
 					try {
 						$this->db->update(
 							$this->dbTablePrefix . 'users',
@@ -663,7 +707,7 @@ final class Auth extends UserManager {
 	 * @throws AuthError if an internal problem occurred (do *not* catch)
 	 */
 	private function updatePassword($userId, $newPassword) {
-		$newPassword = password_hash($newPassword, PASSWORD_DEFAULT);
+		$newPassword = \password_hash($newPassword, \PASSWORD_DEFAULT);
 
 		try {
 			$this->db->update(
@@ -941,7 +985,7 @@ final class Auth extends UserManager {
 			);
 		}
 		elseif ($username !== null) {
-			$username = trim($username);
+			$username = \trim($username);
 
 			// attempt to look up the account information using the specified username
 			$userData = $this->getUserDataByUsername(
@@ -957,9 +1001,9 @@ final class Auth extends UserManager {
 
 		$password = self::validatePassword($password);
 
-		if (password_verify($password, $userData['password'])) {
+		if (\password_verify($password, $userData['password'])) {
 			// if the password needs to be re-hashed to keep up with improving password cracking techniques
-			if (password_needs_rehash($userData['password'], PASSWORD_DEFAULT)) {
+			if (\password_needs_rehash($userData['password'], \PASSWORD_DEFAULT)) {
 				// create a new hash from the password and update it in the database
 				$this->updatePassword($userData['id'], $password);
 			}
@@ -1027,7 +1071,7 @@ final class Auth extends UserManager {
 	 */
 	private function getUserDataByEmailAddress($email, array $requestedColumns) {
 		try {
-			$projection = implode(', ', $requestedColumns);
+			$projection = \implode(', ', $requestedColumns);
 			$userData = $this->db->selectRow(
 				'SELECT ' . $projection . ' FROM ' . $this->dbTablePrefix . 'users WHERE email = ?',
 				[ $email ]
@@ -1058,7 +1102,7 @@ final class Auth extends UserManager {
 				'SELECT COUNT(*) FROM ' . $this->dbTablePrefix . 'users_resets WHERE user = ? AND expires > ?',
 				[
 					$userId,
-					time()
+					\time()
 				]
 			);
 
@@ -1093,8 +1137,8 @@ final class Auth extends UserManager {
 	private function createPasswordResetRequest($userId, $expiresAfter, callable $callback) {
 		$selector = self::createRandomString(20);
 		$token = self::createRandomString(20);
-		$tokenHashed = password_hash($token, PASSWORD_DEFAULT);
-		$expiresAt = time() + $expiresAfter;
+		$tokenHashed = \password_hash($token, \PASSWORD_DEFAULT);
+		$expiresAt = \time() + $expiresAfter;
 
 		try {
 			$this->db->insert(
@@ -1111,7 +1155,7 @@ final class Auth extends UserManager {
 			throw new DatabaseError();
 		}
 
-		if (isset($callback) && is_callable($callback)) {
+		if (\is_callable($callback)) {
 			$callback($selector, $token);
 		}
 		else {
@@ -1151,8 +1195,8 @@ final class Auth extends UserManager {
 
 		if (!empty($resetData)) {
 			if ((int) $resetData['resettable'] === 1) {
-				if (password_verify($token, $resetData['token'])) {
-					if ($resetData['expires'] >= time()) {
+				if (\password_verify($token, $resetData['token'])) {
+					if ($resetData['expires'] >= \time()) {
 						$newPassword = self::validatePassword($newPassword);
 
 						// update the password in the database
@@ -1307,7 +1351,7 @@ final class Auth extends UserManager {
 	 * @param int $userId the user's ID
 	 */
 	private function setUserId($userId) {
-		$_SESSION[self::SESSION_FIELD_USER_ID] = intval($userId);
+		$_SESSION[self::SESSION_FIELD_USER_ID] = (int) $userId;
 	}
 
 	/**
@@ -1692,24 +1736,6 @@ final class Auth extends UserManager {
 		return new Administration($this->db, $this->dbTablePrefix);
 	}
 
-	/**
-	 * Creates the cookie settings that will be used to create and update cookies on the client
-	 *
-	 * @return array the cookie settings
-	 */
-	private function createCookieSettings() {
-		// get the default cookie settings
-		$params = session_get_cookie_params();
-
-		// check if we want to send cookies via SSL/TLS only
-		$params['secure'] = $params['secure'] || $this->useHttps;
-		// check if we want to send cookies via HTTP(S) only
-		$params['httponly'] = $params['httponly'] || !$this->allowCookiesScriptAccess;
-
-		// return the modified settings
-		return $params;
-	}
-
 	/**
 	 * Creates a UUID v4 as per RFC 4122
 	 *
@@ -1719,14 +1745,57 @@ final class Auth extends UserManager {
 	 * @author Jack @ Stack Overflow
 	 */
 	public static function createUuid() {
-		$data = openssl_random_pseudo_bytes(16);
+		$data = \openssl_random_pseudo_bytes(16);
 
 		// set the version to 0100
-		$data[6] = chr(ord($data[6]) & 0x0f | 0x40);
+		$data[6] = \chr(\ord($data[6]) & 0x0f | 0x40);
 		// set bits 6-7 to 10
-		$data[8] = chr(ord($data[8]) & 0x3f | 0x80);
+		$data[8] = \chr(\ord($data[8]) & 0x3f | 0x80);
 
-		return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($data), 4));
+		return \vsprintf('%s%s-%s-%s-%s-%s%s%s', \str_split(\bin2hex($data), 4));
+	}
+
+	/**
+	 * Generates a unique cookie name for the given descriptor based on the supplied seed
+	 *
+	 * @param string $descriptor a short label describing the purpose of the cookie, e.g. 'session'
+	 * @param string|null $seed (optional) the data to deterministically generate the name from
+	 * @return string
+	 */
+	public static function createCookieName($descriptor, $seed = null) {
+		// use the supplied seed or the current UNIX time in seconds
+		$seed = ($seed !== null) ? $seed : \time();
+
+		foreach (self::COOKIE_PREFIXES as $cookiePrefix) {
+			// if the seed contains a certain cookie prefix
+			if (\strpos($seed, $cookiePrefix) === 0) {
+				// prepend the same prefix to the descriptor
+				$descriptor = $cookiePrefix . $descriptor;
+			}
+		}
+
+		// generate a unique token based on the name(space) of this library and on the seed
+		$token = Base64::encodeUrlSafeWithoutPadding(
+			\md5(
+				__NAMESPACE__ . "\n" . $seed,
+				true
+			)
+		);
+
+		return $descriptor . '_' . $token;
+	}
+
+	/**
+	 * Generates a unique cookie name for the 'remember me' feature
+	 *
+	 * @param string|null $sessionName (optional) the session name that the output should be based on
+	 * @return string
+	 */
+	public static function createRememberCookieName($sessionName = null) {
+		return self::createCookieName(
+			'remember',
+			($sessionName !== null) ? $sessionName : \session_name()
+		);
 	}
 
 }

src/UserManager.php

@@ -40,10 +40,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 +103,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 +134,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 +145,7 @@ abstract class UserManager {
 					'password' => $password,
 					'username' => $username,
 					'verified' => $verified,
-					'registered' => time()
+					'registered' => \time()
 				]
 			);
 		}
@@ -180,7 +180,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',
@@ -195,7 +195,7 @@ abstract class UserManager {
 			throw new UnknownUsernameException();
 		}
 		else {
-			if (count($users) === 1) {
+			if (\count($users) === 1) {
 				return $users[0];
 			}
 			else {
@@ -216,9 +216,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 +237,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 +265,10 @@ abstract class UserManager {
 	protected function createConfirmationRequest($userId, $email, callable $callback) {
 		$selector = self::createRandomString(16);
 		$token = self::createRandomString(16);
-		$tokenHashed = password_hash($token, PASSWORD_DEFAULT);
+		$tokenHashed = \password_hash($token, \PASSWORD_DEFAULT);
 
 		// the request shall be valid for one day
-		$expires = time() + self::CONFIRMATION_REQUESTS_TTL_IN_SECONDS;
+		$expires = \time() + self::CONFIRMATION_REQUESTS_TTL_IN_SECONDS;
 
 		try {
 			$this->db->insert(
@@ -286,7 +286,7 @@ abstract class UserManager {
 			throw new DatabaseError();
 		}
 
-		if (isset($callback) && is_callable($callback)) {
+		if (\is_callable($callback)) {
 			$callback($selector, $token);
 		}
 		else {

tests/index.php

@@ -15,33 +15,34 @@
  */
 
 // 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('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) {
@@ -98,11 +99,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>';
 						};
 					}
@@ -177,11 +178,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 +203,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 +228,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>';
 					});
 
@@ -320,11 +321,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 +357,13 @@ 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'] === 'logOutAndDestroySession') {
+				$auth->logOutAndDestroySession();
 
 				return 'ok';
 			}
@@ -530,56 +536,64 @@ function showDebugData(\Delight\Auth\Auth $auth, $result) {
 	echo '<pre>';
 
 	echo 'Last operation' . "\t\t\t\t";
-	var_dump($result);
+	\var_dump($result);
 	echo 'Session ID' . "\t\t\t\t";
-	var_dump(session_id());
+	\var_dump(\session_id());
 	echo "\n";
 
 	echo '$auth->isLoggedIn()' . "\t\t\t";
-	var_dump($auth->isLoggedIn());
+	\var_dump($auth->isLoggedIn());
 	echo '$auth->check()' . "\t\t\t\t";
-	var_dump($auth->check());
+	\var_dump($auth->check());
 	echo "\n";
 
 	echo '$auth->getUserId()' . "\t\t\t";
-	var_dump($auth->getUserId());
+	\var_dump($auth->getUserId());
 	echo '$auth->id()' . "\t\t\t\t";
-	var_dump($auth->id());
+	\var_dump($auth->id());
 	echo "\n";
 
 	echo '$auth->getEmail()' . "\t\t\t";
-	var_dump($auth->getEmail());
+	\var_dump($auth->getEmail());
 	echo '$auth->getUsername()' . "\t\t\t";
-	var_dump($auth->getUsername());
+	\var_dump($auth->getUsername());
 
 	echo '$auth->getStatus()' . "\t\t\t";
-	echo convertStatusToText($auth);
+	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));
+	\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));
+	\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));
+	\var_dump($auth->hasAllRoles(\Delight\Auth\Role::DEVELOPER, \Delight\Auth\Role::MANAGER));
 
 	echo "\n";
 
 	echo '$auth->isRemembered()' . "\t\t\t";
-	var_dump($auth->isRemembered());
+	\var_dump($auth->isRemembered());
 	echo '$auth->getIpAddress()' . "\t\t\t";
-	var_dump($auth->getIpAddress());
+	\var_dump($auth->getIpAddress());
 	echo "\n";
 
+	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());
+	\var_dump(\Delight\Auth\Auth::createRandomString());
 	echo 'Auth::createUuid()' . "\t\t\t";
-	var_dump(\Delight\Auth\Auth::createUuid());
+	\var_dump(\Delight\Auth\Auth::createUuid());
 
 	echo '</pre>';
 }
@@ -621,8 +635,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 +660,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,14 +672,17 @@ 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 '<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="logOutAndDestroySession" />';
+	echo '<button type="submit">Log out and destroy session</button>';
+	echo '</form>';
 }
 
 function showGuestUserForm() {
-	showGeneralForm();
-
 	echo '<h1>Public</h1>';
 
 	echo '<form action="" method="post" accept-charset="utf-8">';
@@ -708,7 +723,7 @@ 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" />';
@@ -759,49 +774,49 @@ 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 '<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 '<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>';
 }