
    Axis--Session.php
    A PHP Object for Maintaining the Values of Variables Across Pages
 
    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 Session object is intended to be used to maintain the values of PHP
    variables across pages for a given user.


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

    Session(&$DB)
        object constructor

    RegisterVariable($GlobalVariableName)
    UnregisterVariable($GlobalVariableName)
        tag or untag a global variable to be preserved between pages

    IsRegistered($VariableName)
        check whether or not a variable has been registered to be preserved

    Get($VariableName)
        retrieve the value of variables


    ----- DETAIL

    Session(&$DB)

    This the constructor function for the object, called automatically when
    an instance of the object is created.  The parameter $DB should be a
    Database object (from Axis--Database.php) that is connected to a database
    containing the appropriate tables as defined in the accompanying file
    Axis--Session--CreateTables.sql.  When the constructor is called it
    checks for a session ID and, if an ID is not found, generates one and 
    writes out the appropriate cookie.  IMPORTANT:  Since it writes out a
    cookie, the Session object must be created before *any* HTML output at
    all is written, including the opening <html> or <header> tags.


    RegisterVariable($GlobalVariableName)
    UnregisterVariable($GlobalVariableName)

    These two functions should be used to indicate to the Session object
    which global variables you want it to maintain between page loads.  The
    variable names are specified without the leading $ character.


    IsRegistered($VariableName)

    This function indicates whether a variable with the specified name is
    currently registered for this session.


    Get($VariableName)

    This function returns the value the variable had when the page was loaded,
    or, if it was registered on the current page, the value at the time of
    registration.


    ----- USAGE

    require_once("Axis--Database.php");
    require_once("Axis--Session.php");
    
    $DB = new Database("user name", "password", "database name");
    $Session = new Session($DB);

    $Session->RegisterVariable("SomeVarOne");
    $Session->RegisterVariable("SomeVarTwo");


    ----- NOTES

    Retrieving critical variables with Get() at the beginning of a page may
    be preferable to referencing global variables because of the way PHP loads
    form values directly into global variables.  If the session has expired or
    for any reason the variable was not registered by a previous page, a
    malicious user could potentially forge the value of the variable if it is
    not retrieved using Get().


