		PHP session library

--------------------------------------------------------------------------------
	Why
--------------------------------------------------------------------------------

Sessions are very useful for web development. Even there is an implementation
with php4 but since some major drawbacks I am still using the one developed for
php3.

This library gives the ability to make script variables persistent between page
views. For example a site requiring logged in user may keep the login screen in
https and leave the security for other pages to the session id since no
username/password is transferred between browser and server when they are saved
in the session.

--------------------------------------------------------------------------------
	Concepts
--------------------------------------------------------------------------------

Script variables to be saved must be global and are passed to the library with
their names. When the session is saved the actual values are taken and saved
into the storage. Upon another page view the session_start_() function loads the
saved data from the storage and makes all saved variables global and registered
in the session. Only a subsequent save is required if only the values are
changed but not the variable set.

Session id generation is flexible - it is left to the user code and a helper
function is supplied (session_get_unique_id) to easily generate secure unique
ids. For example an application may save into sessions some content naming the
session ids after something meaningful and then reuse the session ids to load
presaved variables.

Generally any php variable can be saved except classes. In this case only class
data is saved and restored. See the PHP manual on serialize/unserialize
functions.

For session data storage the library supports two types - MySQL and Oracle SQL
servers. File based sessions may be implemented very easy but still are not.

--------------------------------------------------------------------------------
	Implementing sessions into your project
--------------------------------------------------------------------------------

The easyest way is to read the example.

The hard way is to read the code and make things yourself.

The example is in exsess.php3

--------------------------------------------------------------------------------
	Authors/History
--------------------------------------------------------------------------------

The code is not only my work, here is a history and list of people.

The startup version was written by Stefan Stoyanov (i've lost the email) under
my specifications. Later on I have made some code cleanup and rewrites. Then the
code was implemented in several projects. In one of them
Peter Pentchev (roam@online.bg) has made some changes, bugfixes, etc. Then I
have added Oracle support with the help of Blagovest Lefterov (kiusa@amexy.com).
Finally I have merged all the reasonable patches into this version.

Older versions of the code are working in the following sites (I skip intranet
projects):

www.orbitel.bg
sms.mtel.net

Send me info on success to update the list.

--------------------------------------------------------------------------------
	Known bugs/features
--------------------------------------------------------------------------------

1. Magic quotes must be set as following (eighter in .htaccess or php(3).ini)

magic_quotes_gpc=on
magic_quotes_runtime=off

2. PHP4 built in session support

This library does not interfere with php4 built in sessions in any way.

3. PHP versions supported

The oldest tested version of PHP was 3.0.15
100% working with 3.0.16, 3.0.17, 4.0.3pl1
Must work fine with any version above 4.0.3 and 3.0.15

4. Function problems

The session_destroy_() function does not support Oracle save type.
It can be added very simply but i haven't the need in my Oracle projects.

5. Session removal upon timeout

In my implementations I am using something like:

echo "delete from sessions where adddate(tstamp,interval 30 minute)<now();" \
|mysql mydatabase -N ...

6. Have you found a bug?

Send me a report or diffs.

--------------------------------------------------------------------------------
	Future development
--------------------------------------------------------------------------------

I have a short list to add
- make session_destroy_() work with Oracle
- implement file based storage (i think about one file per session, using
		filesystem date as tstamp)

--------------------------------------------------------------------------------
	Function list with short description
--------------------------------------------------------------------------------

// Remove a session from the storage
function session_destroy_($sess_name="sid")

// Returns true/false if a given session id exits in the storage
function session_exist($sess_id)

// Save data in the current session to the storage
function session_save($sess_name="sid")

// Initialize session code
function session_start_($sess_name="sid")

// Generate new session id assuring that no session with the given id exists in
	the storage
function session_get_unique_id()

// Register variable in the session, the variable's value is read when
	session_save is called
function session_register_($var_name,$sess_name="sid")

// Remove a registered variable form the session
function session_unregister_($var_name,$sess_name="sid")

--------------------------------------------------------------------------------
	Conact me
--------------------------------------------------------------------------------

Boian Bonev
email to: sessions@bonev.com
web site: http://bonev.com/s

the latest version is available from the website

