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 

     DEPENDENCIES:  
 
        - 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.
        
        RETURN VALUE:  
            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
            
        ARGUMENTS
            $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
        
        COOKIES
            $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.
            
        RETURN VALUES
            If successful, return true; otherwise, false.  If errors arose, they are noted in the property "errorMessage", and also logged
            on server
     */    
    
    
    
    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
     */