Document optional database name, schema or other qualifier in README

README.md

@@ -124,6 +124,8 @@ During development, you may want to disable the request limiting or throttling p
 
 During the lifetime of a session, some user data may be changed remotely, either by a client in another session or by an administrator. That means this information must be regularly resynchronized with its authoritative source in the database, which this library does automatically. By default, this happens every five minutes. If you want to change this interval, pass a custom interval in seconds to the constructor as the fifth argument, which is named `$sessionResyncInterval`.
 
+If all your database tables need a common database name, schema name, or other qualifier that must be specified explicitly, you can optionally pass that qualifier to the constructor as the sixth parameter, which is named `$dbSchema`.
+
 ### Registration (sign up)
 
 ```php
@@ -148,6 +150,8 @@ catch (\Delight\Auth\TooManyRequestsException $e) {
 }
 ```
 
+**Note:** The anonymous callback function is a [closure](http://php.net/manual/en/functions.anonymous.php). Thus, besides its own parameters, only [superglobals](http://php.net/manual/en/language.variables.superglobals.php) like `$_GET`, `$_POST`, `$_COOKIE` and `$_SERVER` are available inside. For any other variable from the parent scope, you need to explicitly make a copy available inside by adding a `use` clause after the parameter list.
+
 The username in the third parameter is optional. You can pass `null` there if you don’t want to manage usernames.
 
 If you want to enforce unique usernames, on the other hand, simply call `registerWithUniqueUsername` instead of `register`, and be prepared to catch the `DuplicateUsernameException`.
@@ -261,6 +265,8 @@ catch (\Delight\Auth\TooManyRequestsException $e) {
 }
 ```
 
+**Note:** The anonymous callback function is a [closure](http://php.net/manual/en/functions.anonymous.php). Thus, besides its own parameters, only [superglobals](http://php.net/manual/en/language.variables.superglobals.php) like `$_GET`, `$_POST`, `$_COOKIE` and `$_SERVER` are available inside. For any other variable from the parent scope, you need to explicitly make a copy available inside by adding a `use` clause after the parameter list.
+
 You should build an URL with the selector and token and send it to the user, e.g.:
 
 ```php
@@ -395,6 +401,8 @@ catch (\Delight\Auth\TooManyRequestsException $e) {
 }
 ```
 
+**Note:** The anonymous callback function is a [closure](http://php.net/manual/en/functions.anonymous.php). Thus, besides its own parameters, only [superglobals](http://php.net/manual/en/language.variables.superglobals.php) like `$_GET`, `$_POST`, `$_COOKIE` and `$_SERVER` are available inside. For any other variable from the parent scope, you need to explicitly make a copy available inside by adding a `use` clause after the parameter list.
+
 For email verification, you should build an URL with the selector and token and send it to the user, e.g.:
 
 ```php
@@ -403,6 +411,8 @@ $url = 'https://www.example.com/verify_email?selector=' . \urlencode($selector)
 
 After the request to change the email address has been made, or even better, after the change has been confirmed by the user, you should send an email to their account’s *previous* email address as an out-of-band notification informing the account owner about this critical change.
 
+**Note:** Changes to a user’s email address take effect in the local session immediately, as expected. In other sessions (e.g. on other devices), the changes may need up to five minutes to take effect, though. This increases performance and usually poses no problem. If you want to change this behavior, nevertheless, simply decrease (or perhaps increase) the value that you pass to the [`Auth` constructor](#creating-a-new-instance) as the argument named `$sessionResyncInterval`.
+
 ### Re-sending confirmation requests
 
 If an earlier confirmation request could not be delivered to the user, or if the user missed that request, or if they just don’t want to wait any longer, you may re-send an earlier request like this:
@@ -441,6 +451,8 @@ catch (\Delight\Auth\TooManyRequestsException $e) {
 }
 ```
 
+**Note:** The anonymous callback function is a [closure](http://php.net/manual/en/functions.anonymous.php). Thus, besides its own parameters, only [superglobals](http://php.net/manual/en/language.variables.superglobals.php) like `$_GET`, `$_POST`, `$_COOKIE` and `$_SERVER` are available inside. For any other variable from the parent scope, you need to explicitly make a copy available inside by adding a `use` clause after the parameter list.
+
 Usually, you should build an URL with the selector and token and send it to the user, e.g. as follows:
 
 ```php
@@ -477,6 +489,8 @@ Additionally, if you store custom information in the session as well, and if you
 $auth->destroySession();
 ```
 
+**Note:** Global logouts take effect in the local session immediately, as expected. In other sessions (e.g. on other devices), the changes may need up to five minutes to take effect, though. This increases performance and usually poses no problem. If you want to change this behavior, nevertheless, simply decrease (or perhaps increase) the value that you pass to the [`Auth` constructor](#creating-a-new-instance) as the argument named `$sessionResyncInterval`.
+
 ### Accessing user information
 
 #### Login state
@@ -704,19 +718,19 @@ function canEditArticle(\Delight\Auth\Auth $auth) {
 
 // ...
 
-if (canEditArticle($app->auth())) {
+if (canEditArticle($auth)) {
     // the user can edit articles here
 }
 
 // ...
 
-if (canEditArticle($app->auth())) {
+if (canEditArticle($auth)) {
     // ... and here
 }
 
 // ...
 
-if (canEditArticle($app->auth())) {
+if (canEditArticle($auth)) {
     // ... and here
 }
 ```
@@ -927,6 +941,8 @@ catch (\Delight\Auth\AmbiguousUsernameException $e) {
 }
 ```
 
+**Note:** Changes to a user’s set of roles take effect in the local session immediately, as expected. In other sessions (e.g. on other devices), the changes may need up to five minutes to take effect, though. This increases performance and usually poses no problem. If you want to change this behavior, nevertheless, simply decrease (or perhaps increase) the value that you pass to the [`Auth` constructor](#creating-a-new-instance) as the argument named `$sessionResyncInterval`.
+
 #### Taking roles away from users
 
 ```php
@@ -959,6 +975,8 @@ catch (\Delight\Auth\AmbiguousUsernameException $e) {
 }
 ```
 
+**Note:** Changes to a user’s set of roles take effect in the local session immediately, as expected. In other sessions (e.g. on other devices), the changes may need up to five minutes to take effect, though. This increases performance and usually poses no problem. If you want to change this behavior, nevertheless, simply decrease (or perhaps increase) the value that you pass to the [`Auth` constructor](#creating-a-new-instance) as the argument named `$sessionResyncInterval`.
+
 #### Checking roles
 
 ```php

composer.json

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

composer.lock

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

src/Administration.php

@@ -20,9 +20,10 @@ final class Administration extends UserManager {
 	/**
 	 * @param PdoDatabase|PdoDsn|\PDO $databaseConnection the database connection to operate on
 	 * @param string|null $dbTablePrefix (optional) the prefix for the names of all database tables used by this component
+	 * @param string|null $dbSchema (optional) the schema name for all database tables used by this component
 	 */
-	public function __construct($databaseConnection, $dbTablePrefix = null) {
-		parent::__construct($databaseConnection, $dbTablePrefix);
+	public function __construct($databaseConnection, $dbTablePrefix = null, $dbSchema = null) {
+		parent::__construct($databaseConnection, $dbTablePrefix, $dbSchema);
 	}
 
 	/**
@@ -270,11 +271,14 @@ final class Administration extends UserManager {
 	 * @see Role
 	 */
 	public function doesUserHaveRole($userId, $role) {
+		if (empty($role) || !\is_numeric($role)) {
+			return false;
+		}
+
 		$userId = (int) $userId;
-		$role = (int) $role;
 
 		$rolesBitmask = $this->db->selectValue(
-			'SELECT roles_mask FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
+			'SELECT roles_mask FROM ' . $this->makeTableName('users') . ' WHERE id = ?',
 			[ $userId ]
 		);
 
@@ -282,6 +286,8 @@ final class Administration extends UserManager {
 			throw new UnknownIdException();
 		}
 
+		$role = (int) $role;
+
 		return ($rolesBitmask & $role) === $role;
 	}
 
@@ -298,7 +304,7 @@ final class Administration extends UserManager {
 		$userId = (int) $userId;
 
 		$rolesBitmask = $this->db->selectValue(
-			'SELECT roles_mask FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
+			'SELECT roles_mask FROM ' . $this->makeTableName('users') . ' WHERE id = ?',
 			[ $userId ]
 		);
 
@@ -425,7 +431,7 @@ final class Administration extends UserManager {
 	private function deleteUsersByColumnValue($columnName, $columnValue) {
 		try {
 			return $this->db->delete(
-				$this->dbTablePrefix . 'users',
+				$this->makeTableNameComponents('users'),
 				[
 					$columnName => $columnValue
 				]
@@ -452,7 +458,7 @@ final class Administration extends UserManager {
 	private function modifyRolesForUserByColumnValue($columnName, $columnValue, callable $modification) {
 		try {
 			$userData = $this->db->selectRow(
-				'SELECT id, roles_mask FROM ' . $this->dbTablePrefix . 'users WHERE ' . $columnName . ' = ?',
+				'SELECT id, roles_mask FROM ' . $this->makeTableName('users') . ' WHERE ' . $columnName . ' = ?',
 				[ $columnValue ]
 			);
 		}
@@ -468,7 +474,7 @@ final class Administration extends UserManager {
 
 		try {
 			$this->db->exec(
-				'UPDATE ' . $this->dbTablePrefix . 'users SET roles_mask = ? WHERE id = ?',
+				'UPDATE ' . $this->makeTableName('users') . ' SET roles_mask = ? WHERE id = ?',
 				[
 					$newRolesBitmask,
 					(int) $userData['id']
@@ -544,7 +550,7 @@ final class Administration extends UserManager {
 	private function logInAsUserByColumnValue($columnName, $columnValue) {
 		try {
 			$users = $this->db->select(
-				'SELECT verified, id, email, username, status, roles_mask FROM ' . $this->dbTablePrefix . 'users WHERE ' . $columnName . ' = ? LIMIT 2 OFFSET 0',
+				'SELECT verified, id, email, username, status, roles_mask FROM ' . $this->makeTableName('users') . ' WHERE ' . $columnName . ' = ? LIMIT 2 OFFSET 0',
 				[ $columnValue ]
 			);
 		}

src/Auth.php

@@ -39,9 +39,10 @@ final class Auth extends UserManager {
 	 * @param string|null $dbTablePrefix (optional) the prefix for the names of all database tables used by this component
 	 * @param bool|null $throttling (optional) whether throttling should be enabled (e.g. in production) or disabled (e.g. during development)
 	 * @param int|null $sessionResyncInterval (optional) the interval in seconds after which to resynchronize the session data with its authoritative source in the database
+	 * @param string|null $dbSchema (optional) the schema name for all database tables used by this component
 	 */
-	public function __construct($databaseConnection, $ipAddress = null, $dbTablePrefix = null, $throttling = null, $sessionResyncInterval = null) {
-		parent::__construct($databaseConnection, $dbTablePrefix);
+	public function __construct($databaseConnection, $ipAddress = null, $dbTablePrefix = null, $throttling = null, $sessionResyncInterval = null, $dbSchema = null) {
+		parent::__construct($databaseConnection, $dbTablePrefix, $dbSchema);
 
 		$this->ipAddress = !empty($ipAddress) ? $ipAddress : (isset($_SERVER['REMOTE_ADDR']) ? $_SERVER['REMOTE_ADDR'] : null);
 		$this->throttling = isset($throttling) ? (bool) $throttling : true;
@@ -114,7 +115,7 @@ final class Auth extends UserManager {
 				if (!empty($parts[0]) && !empty($parts[1])) {
 					try {
 						$rememberData = $this->db->selectRow(
-							'SELECT a.user, a.token, a.expires, b.email, b.username, b.status, b.roles_mask, b.force_logout FROM ' . $this->dbTablePrefix . 'users_remembered AS a JOIN ' . $this->dbTablePrefix . 'users AS b ON a.user = b.id WHERE a.selector = ?',
+							'SELECT a.user, a.token, a.expires, b.email, b.username, b.status, b.roles_mask, b.force_logout FROM ' . $this->makeTableName('users_remembered') . ' AS a JOIN ' . $this->makeTableName('users') . ' AS b ON a.user = b.id WHERE a.selector = ?',
 							[ $parts[0] ]
 						);
 					}
@@ -156,7 +157,7 @@ final class Auth extends UserManager {
 				// fetch the authoritative data from the database again
 				try {
 					$authoritativeData = $this->db->selectRow(
-						'SELECT email, username, status, roles_mask, force_logout FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
+						'SELECT email, username, status, roles_mask, force_logout FROM ' . $this->makeTableName('users') . ' WHERE id = ?',
 						[ $this->getUserId() ]
 					);
 				}
@@ -353,7 +354,7 @@ final class Auth extends UserManager {
 
 			try {
 				$expectedHash = $this->db->selectValue(
-					'SELECT password FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
+					'SELECT password FROM ' . $this->makeTableName('users') . ' WHERE id = ?',
 					[ $this->getUserId() ]
 				);
 			}
@@ -496,7 +497,7 @@ final class Auth extends UserManager {
 
 		try {
 			$this->db->insert(
-				$this->dbTablePrefix . 'users_remembered',
+				$this->makeTableNameComponents('users_remembered'),
 				[
 					'user' => $userId,
 					'selector' => $selector,
@@ -566,7 +567,7 @@ final class Auth extends UserManager {
 		// update the timestamp of the user's last login
 		try {
 			$this->db->update(
-				$this->dbTablePrefix . 'users',
+				$this->makeTableNameComponents('users'),
 				[ 'last_login' => \time() ],
 				[ 'id' => $userId ]
 			);
@@ -620,7 +621,7 @@ final class Auth extends UserManager {
 
 		try {
 			$confirmationData = $this->db->selectRow(
-				'SELECT a.id, a.user_id, a.email AS new_email, a.token, a.expires, b.email AS old_email FROM ' . $this->dbTablePrefix . 'users_confirmations AS a JOIN ' . $this->dbTablePrefix . 'users AS b ON b.id = a.user_id WHERE a.selector = ?',
+				'SELECT a.id, a.user_id, a.email AS new_email, a.token, a.expires, b.email AS old_email FROM ' . $this->makeTableName('users_confirmations') . ' AS a JOIN ' . $this->makeTableName('users') . ' AS b ON b.id = a.user_id WHERE a.selector = ?',
 				[ $selector ]
 			);
 		}
@@ -634,7 +635,7 @@ final class Auth extends UserManager {
 					// invalidate any potential outstanding password reset requests
 					try {
 						$this->db->delete(
-							$this->dbTablePrefix . 'users_resets',
+							$this->makeTableNameComponents('users_resets'),
 							[ 'user' => $confirmationData['user_id'] ]
 						);
 					}
@@ -645,7 +646,7 @@ final class Auth extends UserManager {
 					// mark the email address as verified (and possibly update it to the new address given)
 					try {
 						$this->db->update(
-							$this->dbTablePrefix . 'users',
+							$this->makeTableNameComponents('users'),
 							[
 								'email' => $confirmationData['new_email'],
 								'verified' => 1
@@ -672,7 +673,7 @@ final class Auth extends UserManager {
 					// consume the token just being used for confirmation
 					try {
 						$this->db->delete(
-							$this->dbTablePrefix . 'users_confirmations',
+							$this->makeTableNameComponents('users_confirmations'),
 							[ 'id' => $confirmationData['id'] ]
 						);
 					}
@@ -817,7 +818,7 @@ final class Auth extends UserManager {
 
 			try {
 				$existingUsersWithNewEmail = $this->db->selectValue(
-					'SELECT COUNT(*) FROM ' . $this->dbTablePrefix . 'users WHERE email = ?',
+					'SELECT COUNT(*) FROM ' . $this->makeTableName('users') . ' WHERE email = ?',
 					[ $newEmail ]
 				);
 			}
@@ -831,7 +832,7 @@ final class Auth extends UserManager {
 
 			try {
 				$verified = $this->db->selectValue(
-					'SELECT verified FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
+					'SELECT verified FROM ' . $this->makeTableName('users') . ' WHERE id = ?',
 					[ $this->getUserId() ]
 				);
 			}
@@ -919,7 +920,7 @@ final class Auth extends UserManager {
 	private function resendConfirmationForColumnValue($columnName, $columnValue, callable $callback) {
 		try {
 			$latestAttempt = $this->db->selectRow(
-				'SELECT user_id, email FROM ' . $this->dbTablePrefix . 'users_confirmations WHERE ' . $columnName . ' = ? ORDER BY id DESC LIMIT 1 OFFSET 0',
+				'SELECT user_id, email FROM ' . $this->makeTableName('users_confirmations') . ' WHERE ' . $columnName . ' = ? ORDER BY id DESC LIMIT 1 OFFSET 0',
 				[ $columnValue ]
 			);
 		}
@@ -1132,7 +1133,7 @@ final class Auth extends UserManager {
 		try {
 			$projection = \implode(', ', $requestedColumns);
 			$userData = $this->db->selectRow(
-				'SELECT ' . $projection . ' FROM ' . $this->dbTablePrefix . 'users WHERE email = ?',
+				'SELECT ' . $projection . ' FROM ' . $this->makeTableName('users') . ' WHERE email = ?',
 				[ $email ]
 			);
 		}
@@ -1158,7 +1159,7 @@ final class Auth extends UserManager {
 	private function getOpenPasswordResetRequests($userId) {
 		try {
 			$requests = $this->db->selectValue(
-				'SELECT COUNT(*) FROM ' . $this->dbTablePrefix . 'users_resets WHERE user = ? AND expires > ?',
+				'SELECT COUNT(*) FROM ' . $this->makeTableName('users_resets') . ' WHERE user = ? AND expires > ?',
 				[
 					$userId,
 					\time()
@@ -1201,7 +1202,7 @@ final class Auth extends UserManager {
 
 		try {
 			$this->db->insert(
-				$this->dbTablePrefix . 'users_resets',
+				$this->makeTableNameComponents('users_resets'),
 				[
 					'user' => $userId,
 					'selector' => $selector,
@@ -1244,7 +1245,7 @@ final class Auth extends UserManager {
 
 		try {
 			$resetData = $this->db->selectRow(
-				'SELECT a.id, a.user, a.token, a.expires, b.resettable FROM ' . $this->dbTablePrefix . 'users_resets AS a JOIN ' . $this->dbTablePrefix . 'users AS b ON b.id = a.user WHERE a.selector = ?',
+				'SELECT a.id, a.user, a.token, a.expires, b.resettable FROM ' . $this->makeTableName('users_resets') . ' AS a JOIN ' . $this->makeTableName('users') . ' AS b ON b.id = a.user WHERE a.selector = ?',
 				[ $selector ]
 			);
 		}
@@ -1262,7 +1263,7 @@ final class Auth extends UserManager {
 
 						try {
 							$this->db->delete(
-								$this->dbTablePrefix . 'users_resets',
+								$this->makeTableNameComponents('users_resets'),
 								[ 'id' => $resetData['id'] ]
 							);
 						}
@@ -1355,7 +1356,7 @@ final class Auth extends UserManager {
 		if ($this->isLoggedIn()) {
 			try {
 				$this->db->update(
-					$this->dbTablePrefix . 'users',
+					$this->makeTableNameComponents('users'),
 					[
 						'resettable' => $enabled ? 1 : 0
 					],
@@ -1384,7 +1385,7 @@ final class Auth extends UserManager {
 		if ($this->isLoggedIn()) {
 			try {
 				$enabled = $this->db->selectValue(
-					'SELECT resettable FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
+					'SELECT resettable FROM ' . $this->makeTableName('users') . ' WHERE id = ?',
 					[ $this->getUserId() ]
 				);
 
@@ -1563,9 +1564,13 @@ final class Auth extends UserManager {
 	 * @see Role
 	 */
 	public function hasRole($role) {
-		$role = (int) $role;
+		if (empty($role) || !\is_numeric($role)) {
+			return false;
+		}
 
 		if (isset($_SESSION) && isset($_SESSION[self::SESSION_FIELD_ROLES])) {
+			$role = (int) $role;
+
 			return (((int) $_SESSION[self::SESSION_FIELD_ROLES]) & $role) === $role;
 		}
 		else {
@@ -1687,7 +1692,7 @@ final class Auth extends UserManager {
 
 		try {
 			$bucket = $this->db->selectRow(
-				'SELECT tokens, replenished_at FROM ' . $this->dbTablePrefix . 'users_throttling WHERE bucket = ?',
+				'SELECT tokens, replenished_at FROM ' . $this->makeTableName('users_throttling') . ' WHERE bucket = ?',
 				[ $key ]
 			);
 		}
@@ -1724,7 +1729,7 @@ final class Auth extends UserManager {
 			// merge the updated bucket into the database
 			try {
 				$affected = $this->db->update(
-					$this->dbTablePrefix . 'users_throttling',
+					$this->makeTableNameComponents('users_throttling'),
 					$bucket,
 					[ 'bucket' => $key ]
 				);
@@ -1738,7 +1743,7 @@ final class Auth extends UserManager {
 
 				try {
 					$this->db->insert(
-						$this->dbTablePrefix . 'users_throttling',
+						$this->makeTableNameComponents('users_throttling'),
 						$bucket
 					);
 				}
@@ -1768,7 +1773,7 @@ final class Auth extends UserManager {
 	 * @return Administration
 	 */
 	public function admin() {
-		return new Administration($this->db, $this->dbTablePrefix);
+		return new Administration($this->db, $this->dbTablePrefix, $this->dbSchema);
 	}
 
 	/**
@@ -1864,7 +1869,7 @@ final class Auth extends UserManager {
 			if (isset($existingSelector)) {
 				// fetch the expiry date for the given selector
 				$existingExpiry = $this->db->selectValue(
-					'SELECT expires FROM ' . $this->dbTablePrefix . 'users_remembered WHERE selector = ? AND user = ?',
+					'SELECT expires FROM ' . $this->makeTableName('users_remembered') . ' WHERE selector = ? AND user = ?',
 					[
 						$existingSelector,
 						$this->getUserId()

src/Exceptions.php

@@ -44,8 +44,6 @@ class AuthError extends \Exception {}
 
 class DatabaseError extends AuthError {}
 
-class DatabaseDriverError extends DatabaseError {}
-
 class MissingCallbackError extends AuthError {}
 
 class HeadersAlreadySentError extends AuthError {}

src/UserManager.php

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