Class for the management of generic user accounts on a site: the underlying database table could have more fields, used by other more site-specific modules
    
Based on the entity "User-access ID" : identifying a particular membership for some user
    
    
DEPENDENCIES:   
    
            - dbasePDO

VERSION:

4.1 corrects a bug in the  addNewAccount  method

public $errorSummary;            // Summary of the last error, if applicable

    public function __construct($dbPDO)
    // Argument:  Object for database operations
 

    
    public function validateUser($dbField, $usernameOrEmail, $attemptedPassword, $marketingSlogan = "")
    /*     Attempt to retrieve the membership record for the user with the provided credentials.
        Verify that the credentials are valid and that the account is active.
    
        ARGUMENTS:
            $dbField             Should be the string "email" or "username"
            $usernameOrEmail
            $attemptedPassword
            $marketingSlogan    An optional string to be returned to the user in case the memberhips has expirerd
            
        RETURN:
            If successful, return the array [ID, username] ; otherwise, return false and set the property "errorSummary" to the reason for failure
     */

    
    
    
    public function reValidatePassword($userID, $attemptedPassword)
    /*     For safety, wheneven a user attempts to make important account changes.
        Return true if re-validation suceeeds, or false otherwise.
     */

    

    public function changePassword($userID, $newPass)
    // Update the given user's password with a hashed version of the given new one

    

    public function listActiveUsers($siteID)
    /*     Return a traversable dataset of ACTIVE users on the specified site, with all the available fields in the database table.
        Example of a way to traverse it:
        
            $allUsers = $siteMembership_object->listActiveUsers($siteID);
            foreach ($allUsers as $user)  {
                print_r($user);
                echo "<br><br>";
            }
     */

    
    
    
    public function addUserToAccount($siteID, $username, $email, $pass, $permissions = 0)
    /*     Add a new user to the current site.
        Return the new userID if all operations were successful, or false othewise
     */

    

    
    public function addNewAccount($name, $email, $pass, $newSiteID = null)
    /*     Add a new account to the site, including a user who is an admin for that account.
        Optionally, accept a value for the new siteID (typically used for sites identified by text codes, such as "e", "s"); 
        if a value isn't provided, the next available table record ID (for example 23) is used (as a string; for example "23").
        Return the new account ID if all operations were successful, or -1 othewise; in case of errors, also set the property "errorSummary"
     */
  
   
    
    
    public function makeAdmin($userID, $siteManager = false)
    /*     Mark the specified user as an admin for their account - and, optionally, also as a Site Manager
        Return true iff successful
     */

    

    
    public function setupDatabase()
    /*     Create the table used for the membership information.  To be used for installing a new site.
        In case of failure, an exception is thrown
     */

    

    
    public function alreadyInstalled()
    // Return true iff this module table is already installed

    

    
    public function lookupUserByEmail($email)
    // Return the full record of the user with the given email address.  If that email occurs in more than one place, the user with the largest ID is picked
 

    public function verifyUserCredentialsAndFetchUserInfo($userAccessID)    
    /*     Extract and return all user-access field values (such as username, email, active flag, etc),
        while also enforcing the account to be active.
        ARGUMENT:    The user's access ID
        RETURN VALUE: an associative array, containing the user's data.  In case of error or record not found (possibly because account was inactive), return false.
     */

    
    
    public function isUserActive($userAccessID)
    /* Verify the validity of the user access ID.  Return true iff an ACTIVE user membership with the given ID is found
     */

    
    
    public function passwordRequirements()
    // Return a string explaining the password requirements.  The message must match the policy set in the method passwordValidateRequirements()
 

    public function passwordValidateRequirements($pass)
    // Enforce password requirements.  Any change needs to be also reflected in the method passwordRequirements()