Class for SITE USER AUTHENTICATION, incl. login/logout management.
Multiple independent websites are supported.
Authenticated user access is implemented by using randomly-generated session ID's, stored in a cookie on the client side,
and in the database on the server side.
The central entity for site authentication is the "User Access ID", which can be thought of as a particular "subscription" (account) of a user to a site.
A particular user might have multiple subscriptions (accounts) on different sites, and even multiple ones on a single site.
The "User Access ID" resolves the particular subscription (account) on a particular site.
On the server side, it makes use of 1 database table:
- A login table (specific to this module), to store the sessionID's
- dbasePDO This in turn, depends on the "logging" class
- cookies Static methods to set, clear, read and check cookies
- logging Use to log messages (diagnostics, etc) on the server
public $loginTable = "entry"; // Name of table used to store the session info
public $db; // An object of the "dbasePDO" class, to interact with the database
public $cookieSession = "pforce"; // Name of cookie with the sessionID
public $cookieUsername = "username"; // Name of cookie used to store the user name
public $cookieOld = "old"; // Name of cookie used to store the first few digits of the old session ID
public $userAccessID = false; // ID that identifies an instance of user access; typically, either a User ID or a Subscription ID. If not logged it, then false
public $errorMessage = ""; // It gets set with an explanatory string in case of errors
public $messageLogger; // An object of the "logging" class
public $allowMultipleLogins = true; // Flag indicating whether the same user account is allowed to be accessed through multiple simultaneous logins
// TO DO: implement a max # of simultaneous logins (?)
public $maxLoginHours = 9; // Login expiration time, in hours. Only applicable if allowMultipleLogins is false
public $loginURL; // URL to re-direct to if login is required but user isn't logged in
function __construct($db, $messageLogger) // CONSTRUCTOR
/* $db: An object of the "dbasePDO" class, to interact with the database
$messageLogger: An object of the "logging" class, to log system messages (such as alerts or diagnostics) into a text file or an HTML file
public function userLoginStatusUnverified()
/* Perform a *minimal* check of whether a user is logged in; only to be used in situations where restricted access isn't important.
RETURN VALUE: if logged in, return the username; otherwise, set the property "errorMessage" with an explanation of the failed login, and return FALSE.
The session ID found in the user's cookie is NOT verified against the database.
This function is a "light" version of userLoginStatus(), suitable for low-protection pages.
Since no cookies are set, this function can be invoked anywhere;
this is handy in situations where the page header has already been sent.
public function userLoginStatus()
/* Perform a THOROUGH CHECK of the user's login status, based on the available session cookie value, checked against the database.
IMPORTANT: this function MUST be invoked PRIOR to outputting any text, since it might set cookies.
If logged in, set the property "userAccessID", and also return that value.
If not logged in, then completely log out user (clear his session variables, cookies, database info),
set the property "errorMessage" with an explanation of the failed login, and return FALSE.
public function validateLoginAndLookupUser()
/* If user's login is validated, return the userAccessID (aka subscriptionID); otherwise, return false
public function loginUser($userAccessID, $username, $stayLogged, $visitorID = false)
/* IMPORTANT: This function, because it may set cookies, must be called before any HTML output is started!
Log in the user with the given ID
$userAccessID Typically, a user ID or a subscription ID
$username Redundant: passed for avoiding an extra database call
$stayLogged Flag indicates whether the login is meant to be persistent upon closing the browser
$visitorID Optional integer, for example to associate a login account with data collected from user prior to login
A database connection is assumed.
For security purposes, a new sessionID is always generated.
The session info is stored in the database table $this->loginTable
$this->cookieSession: the session ID (also stored in the database)
$this->cookieUsername: for convenient access by low-value pages.
$this->cookieOld: the first few digits of the last sessionID, to clear old session values that may still linger around.
This is useful for garbage-collecting of one-time logins in cases
where the user closes the browser w/o logging out.
If successful, return true; otherwise, false. If errors arose, they are noted in the property "errorMessage", and also logged
public function logout($all = false)
/* IMPORTANT: This function, because it may set cookies, must be called before any HTML output is started
If the $all flag is set, then ALL login sessions by the current user (e.g. on different devices or browsers) are terminated.
The username is returned (handy to greet goodbye to the user.)
public function enforceLogin($loginPage = false)
/* Re-direct user to login page if not logged in. Perform a THOROUGH CHECK for the login status.
If user is logged in, return the userAccessID.
The database connection gets started if needed.
[Note: if using the "pageBuilder" module, this function is only used for pages that don't employ the startPage() function]
public function redirectToLoginPage($loginPage)
/* Redirect user to the specified login page, and exit.
A full URL is recommended over a relative path, to cover situations where the request comes from any pages in the site.
The loginPage may not include a # fragment
public function loginCount($userAccessID)
/* Return the number of logins that the user has done.
Handy to optionally pass a login count to the login splash page
public function setupDatabase()
/* Create the table used for managing the logins. To be used for installing a new site.
In case of failure, an exception is thrown