BSDM: Badly-Documented Session Management
-----------------------------------------
(A Simple File-based Session Management library for PHP 3 and 4)
By Matt Robinson (http://www.lazycat.org) (C) 2000

Version: 11-May-2000

Overview
--------

This is a simple file-based session-management library for PHP3 and PHP4
(Though PHP4 has its own superior session-management, so you don't really
need this at all, unless you want to make cross-portable scripts that 
don't rely on PHP4). 

It stores one (and one only) variable in a session file stored on the web
server. A session id is returned and also stored in a cookie on the 
user's web browser - this is used to load the session data on subsequent
requests. Cookies aren't required for session management if you append
the URL you are calling with the session id (at the cost of making your
URLs longer and uglier. I leave it to the discretion of the programmer to
decide whether or not to support cookie-less browsers).

Please read the NOTES section below before you start using this library!


Garbage Collection
------------------

Garbage collection is based on the last-modified date of a designated 
"cull file", whose only purpose is to store the date of the last 
collection. Session files older than the stored threshold are deleted.
Collection is triggered on creation or loading of a session, so as 
long as your site gets a hit more often than the cull threshold (by 
default, 15 minutes) you won't have a huge excess of useless session
files. 


Security
--------

Session IDs are cryptographically secure and utterly unpredictable, so
as long as you make sure that your session-data folder is unreadable 
by sources other than this session library, the data is secure. If your
PHP setup doesn't allow the accessing of files outside the public HTML
folder, then try making a .htaccess file in that folder with the line
"deny from all". If your server isn't Apache, you'll have to find your
own solution, sorry. 


Session data
------------

The session data is only one variable, but that variable can be an array
or array of arrays (or array of arrays of arrays if you're twisted).

For example: 
    $session_data = array("username" => $user, "password_hash" => $phash);
  Or:
    $session_data[] = array("item" => "pear", "category" => "fruit");
    $session_data[] = array("item" => "chair", "category" => "furniture");


How it all works
----------------

Create a new session with a call to the create_session() function:

   $sid = create_session();

This returns a session id and sets a cookie (called $sid) containing that id.
You MUST call this before anything is output by PHP. That means it needs to 
go before the <HTML> part of your file. (You can get around this by enabling 
output buffering in your PHP configuration, at the cost of some speed - the 
entire script has to run before any of it is sent to the user. Check your PHP 
manual to find out how to do this.. or just create the session at the start
of your script and save yourself the hassle).

Now you can save data to the session file at any point in your script. 
The write_session(id, data) function writes to the session file. It 
overwrites the existing data, so make sure you send it ALL the data you
want to save, not just new data. You can call this more than once in a 
script though:

    $session_data = array("username" => $user, "password_hash" => $phash);

    if (write_session($sid, $session_data)) {
       echo "Success!";
    }


Load session data with the load_session($id) function. It will return a 
variable containing the saved data. It does -some- checking on the 
validity of the session id passed to it, but it's by no means exhaustive.

    if ($sid) { 
       // Session exists, retrieve data
       $session_data = load_session($sid);
    } else { 
       // Create a new session.
       $sid = create_session(); 
    }


If you believe that everyone visiting your site will have cookies enabled, 
you need only use the above code to load session data in every page that
uses it. If you're a realist, you'll want to include the session id on the
URL too:

     $url = "$PHP_SELF?sid=$sid";
     echo "<FORM method=post action=\"$url\">";

   and

     <A href="another_page.php<? echo "?sid=$sid"; ?>">Link to another page</A>

Delete a session with kill_session($sid):

     if (($logout == 1) && $sid) {
        kill_session($sid);
        $sid = create_session();
     }

It's a good idea to create a new session in a situation like a page with a
log-in. When someone logs out, we don't want a new session to have the same
id as the old one.. it's potentially unpleasant. Creating a new session 
doesn't actually create a session file, so there's little performance hit,
and if you choose to create a new session later, there's no big deal.


NOTES
-----

I've tried to make sure that BDSM's name-space doesn't interfere with yours - 
that is, it won't create any global variables or external variables other than
$sid, the session id, (which gets set as a cookie) and the function names in
the library. 

If you want the session variable $sid to have a different name, you'll have to 
go in and manually edit the code. All the other user preferences are stored in 
the first function, session_prefs(), so you can easily change the setup without
having to understand my code. The defaults should be okay, as long as you create
a folder called ./tmp/ in the folder where your scripts are called.

To use these functions in your scripts, use the require() function to load the
file. Do it at the beginning of scripts that use session management, and make
sure you call create_session() before you print anything to the browser.

  require("./bdsm_session.php3");
  $sid = create_session();

Finally, if you use it and it works, let me know! If you use it and it doesn't 
work, let me know too.. I might have one of those rare moments where I'm not
busy and don't mind looking at other people's code. If you use it and it
doesn't work, find that it's a problem with my code and then fix it, let me know!
I'd much rather someone else fixed it and told me what was wrong than me actually
do any work ;)

Enjoy!

DISCLAIMER
----------

Whatever it is, it's not my fault! I cannot and will not accept any 
responsibility for anything detrimental happening to your scripts, 
your server, your computer, or your mind that happens as a direct
result of using my scripts. Use these scripts at your own risk! I 
make no promises as to their quality or ability.

May contain traces of peanut.