
    Axis--User.php
    A PHP Object for Handling User Information
 
    Copyright 1999-2001 Axis Data
    This code is free software that can be used or redistributed under the
    terms of Version 2 of the GNU General Public License, as published by the
    Free Software Foundation (http://www.fsf.org).
 
    Author:  Edward Almasy (almasy@axisdata.com)
 
    Part of the AxisPHP library
    For more information see http://www.axisdata.com/AxisPHP/


    ----- CONTEXT

    The User object supports the maintenance of logging users in and out of
    a site and stores information about those users.


    ----- SYNOPSIS
 
    require_once("Axis--User.php");

    User(&$SessionOrDB, $UserInfo=NULL)
        object constructor

    CreateNewUser($UserName, $Password, $PasswordAgain)
    CreateNewUserWithEMailedPassword($UserName, $EMail, $EMailAgain, 
            $TemplateFile = "Axis--User--EMailTemplate.txt")
        create new user

    Login($UserName, $Password)
    Logout()
        log existing using into or out of session

    IsLoggedIn()
    IsNotLoggedIn()
        test whether user is logged in or not

    ChangePassword($OldPassword, $NewPassword, $NewPasswordAgain)
        change password for logged in user

    Get($FieldName)
    GetDate($FieldName, $Format = "")
    Set($FieldName, $NewValue)
        get or set values associated with logged in user

    HasPriv($Privilege)
        check whether user has specified privilege

    GivePriv($Privilege)
        grant specified privilege to user

    GetPrivList()
    SetPrivList($NewSettings)
        get or set privileges as an array

    Status()
    StatusMessage()
        return status (numerical or text message) of last method call


    ----- DETAIL

    User(&$SessionOrDB, $UserInfo=NULL)

    This the constructor function for the object, called automatically when
    an instance of the object is created.  The parameter $SessionOrDb can be
    either a Database object (from Axis--Database.php) or a Session object
    (from Axis--Session.php).  In either case the database passed in (or the
    database used to create the Session object) should hold the user tables
    created with Axis--User--CreateTables.sql.  If a Database object is passed
    in then the UserInfo parameter can be either a UserID or a UserName value.
    If the parameter is a UserID value it may require a cast to "(int)" for it
    to be recognized as such.  The Login() and Logout() functions can only be
    used with a User object that was created with a Session value.
    (See NOTES below for more info on the User() constructor method.)


    Login($UserName, $Password)

    The Login() function checks the user name and password against those
    stored in the database and, if they are correct, logs the user into the
    session.  The following error codes may be returned by Login():  
    U_NOSUCHUSER and U_BADPASSWORD.  The Login() function returns U_OKAY upon
    successful login.


    Logout()

    The Logout() function causes the user information to be discarded for 
    the session, although this is dependent on the SaveState() function being
    called for the session before the page exits.  The Logout() function does
    not return a value.


    ChangePassword($OldPassword, $NewPassword, $NewPasswordAgain)

    This function checks the old password against the password stored in the
    database and, if those match, checks the new password for legality (must
    be at least 6 characters long) and, if that passes, checks the two copies
    of the new password against each other.  If all of those tests are passed,
    the user's password is updated in the database.  The following error codes
    may be returned by this function:  U_BADPASSWORD, U_NOTLOGGEDIN, 
    U_ILLEGALPASSWORD, and U_PASSWORDSDONTMATCH.  If the function succeeds it
    returns U_OKAY.


    CreateNewUser($UserName, $Password, $PasswordAgain)

    As might be expected, this function creates a new user account in the
    database.  It can return the following error codes:  U_ILLEGALUSERNAME,
    (user names must be 2-24 alphanumeric charactes), U_ILLEGALPASSWORD (must
    be at least 6 characters), U_PASSWORDSDONTMATCH, and U_DUPLICATEUSERNAME.
    If the function succeeds it returns U_OKAY.  NOTE:  This function *does
    not* log the user in -- if you want the user to be logged in at the same
    time the new user account is created follow it up with a call to Login().

    CreateNewUserWithEMailedPassword($UserName, $EMail, $EMailAgain, 
            $TemplateFile = "Axis--User--EMailTemplate.txt")

    This function creates a new user account with a random password, and
    e-mails that password to the user at the address supplied.  In addition to
    the error codes that CreateNewUser() may return, this function can return
    U_EMAILSDONTMATCH, U_ILLEGALEMAIL, and U_MAILINGERROR.


    Get($FieldName)
    GetDate($FieldName, $Format = "")
    Set($FieldName, $NewValue)

    These functions get and set values in the user record.  The $FieldName
    parameter should contain the name of the SQL database field containing
    the value to be retrieved or set.  Both functions can return U_NOTLOGGEDIN
    and Set() returns U_OKAY upon success.  The GetDate() function returns a
    value formatted with the SQL DATE_FORMAT function.


    HasPriv($Privilege)
    GivePriv($Privilege)

    These two functions get and set a user privilege flag, respectively.
    Privileges are arbitrary numeric values, defined by the application.


    GetPrivList()
    SetPrivList($NewSettings)

    These are convenience functions that allow retrieval or update of a
    user's privileges via an array of privilege values.  A common use for this
    would be when creating an option list of privilege values for a user
    record editing page, or when setting privilege values returned from a user
    editing page.


    ----- USAGE

    require_once("Axis--User.php");

    # define user privilege levels
    define("PRIV_REGISTERED", 1);
    define("PRIV_ADMIN", 2);
    define("PRIV_SYSADMIN", 3);

    # connect to database and restore session and user objects
    $DB = new Database("user name", "password", "database name");
    $Session = new Session($DB);
    $User = new User($Session);

    # log user in
    $Result = $User->Login($F_UserName, $F_Password);
    if ($Result == U_OKAY)
    {
        (user is logged in)

        # check whether to display administrative options
        if ($User->HasPriv(PRIV_ADMIN))
        {
            (user has PRIV_ADMIN privilege set)
        }
    }

            :
            :
        (other page content)
            :
            :


    ----- NOTES

    - Creating a User object with a Session parameter is intended for handling
        the current user of the site.  Creating a User object with Database and
        user ID or user name parameters is intended for situations where you
        need to obtain information about or manipulate records for users other
        than the user currently logged into the site (e.g. when the site
        administrator needs to edit or review settings for a given user).


