Class: Session
- Package: saf.Session
- Author: John Luxford <lux@simian.ca>
- Copyright: Copyright (C) 2001-2003, Simian Systems Inc.
- License: http://www.sitellite.org/index/license Simian Open Software License
- Version: 2.6, 2003-04-23, $Id: Session.php,v 1.6 2007/10/06 00:06:30 lux Exp $
- Access: public
Session is a class that manages visitor sessions.
Note: Session does not handle anonymous sessions, but
rather serves as a validation process for login-only site components.
Session is relatively easy to integrate into web sites, but
relies on a number of other Sitellite classes, such as
Cookie, and CGI. It is also easy to extend in functionality, as we
did with the SitelliteSession class by adding Sitellite CMS-specific
permission functions.
Note: mt_srand() must also be called prior to creating a Session object,
because the random number generator must be seeded.
New in 2.0:
- This is a complete rewrite that breaks backward compatibility with 1.x.
It offers an abstracted Session class that uses drivers for both the
validation source and the visitor protocol handler. Initially, there
is only one source driver, which is a database driver, and there are
two handler drivers, one for storing session ids using cookies and the
other challenges the client with an HTTP Basic authentication request.
New in 2.2:
- Added a session store driver system, which allows variables to be
assigned to a session. This required a change in the parameter order
of the constructor method (sorry!), so you'll have to make a tiny change
there. Also required the addition of two new properties and four new
methods:
- $store (store driver object)
- $autoSave (whether to call save() after each call to set())
- setStoreProperties ()
- get ()
- set ()
- append()
- save ()
New in 2.4:
- Added session_get(), session_set(), session_append(), and session_save()
global functions that simply call the equivalent methods on a global
$session object.
New in 3.0:
- Added the use of a new SessionAcl package which provides access control
functionality to this package, meant to serve as a replacement for the
SitelliteSession overriding package. SessionAcl adds finer granularity
in defining and controlling users through the separation of read and
write access, and also boasts a new INI-based definition format in
place of the MySQL sitellite_role, sitellite_team, sitellite_access,
and sitellite_status tables. This will not only improve flexibility,
but it should also make this package significantly faster too.
- Broke backward compatibility in the parameters of the allowed()
method. As compared to the SitelliteSession package, this also
eliminates the getPermissions() method, which is replaced by internal
handling of this functionality.
Historical
----------
New in 1.2:
- Updated to use $site->webpath instead of $site->path, which is
deprecated in saf.Site.
New in 1.4:
- Added the ability to make accounts pending, so that they must be verified
via email. This is done by storing a 24 character random string,
preceded by 'PENDING:' in the $sidcol column. This key string can be
generated with the new makePendingKey() method.
New in 1.6:
- Traded $tpl->fill() calls for sprintf(), which should increase
performance a little.
- Moved the encryption of the password field into the PHP level, so as to
eliminate the reliance on MySQL-specific functions (ie. password()).
Unfortunately, this breaks backward compatibility and all passwords will
need to be reset, since both MySQL's password() and PHP's crypt() are
one-way encryption methods.
New in 1.8:
- Added the following methods as aliases of properties or methods of a
global $session object: session_username(), session_valid(),
session_get(), session_set(), session_append(), and session_save().
Usage Example
<?php
// seed the "better" random number generator
mt_srand ((double) microtime () * 1000000);
$sessionCookieName = 'cisforcookie';
$sessionHandler = 'Cookie';
$sessionSource = 'Database';
list ($user, $pass, $id) = Session::gatherParameters ($sessionHandler, $sessionCookieName);
$session = new Session ($sessionHandler, $sessionSource, $user, $pass, $id);
// time out in 1 hour
$session->setTimeout (3600);
$session->setSourceProperties (array (
'database' => 'db',
));
$session->setHandlerProperties (array (
'cookiename' => 'cisforcookie',
'cookiedomain' => 'www.yourwebsite.com',
'cookiepath' => '/',
));
$session->start ();
if ($session->error) {
// something is not right
echo $session->error;
} elseif ($session->valid) {
// valid session
// put all of your private stuff here
} else {
// invalid or new session
$session->sendAuthRequest ();
}
?>
Return to Top
Properties
$access = array ()
$status = array ()
$roles = array ()
$teams = array ()
$resources = array ()
$user = array ()
$prefs = array ()
$_prefs = array ()
$path
$realm
$cancelmessage = 'You do not have permission to access this resource.'
$cookiename = 'sitellite_session_id'
Name of the cookie. Defaults to 'sitellite_session_id'.
$cookieexpires = 0
Expiration of cookie. Defaults to 0, which means the cookie
will expire when the browser closes.
$cookiedomain
Domain value of the cookie.
$cookiepath = '/'
Path value of the cookie. Defaults to '/'.
$cookiesecure = 0
Secure value of the cookie. May be 1 or 0, and defaults to 0.
$usernamefield = 'username'
The name of the username field in the form (uses saf.MailForm)
created by sendAuthRequest(). Defaults to 'username'.
$passwordfield = 'password'
The name of the password field in the form
created by sendAuthRequest(). Defaults to 'password'.
$hiddenfields = array ()
A list of hidden form fields and their values.
$usernametext = 'Username'
The alt text of the username field in the form
created by sendAuthRequest(). Defaults to 'Username'.
$passwordtext = 'Password'
The alt text of the password field in the form
created by sendAuthRequest(). Defaults to 'Password'.
$submittext = 'Sign In'
The alt text of the submit button in the form
created by sendAuthRequest(). Defaults to 'Sign In'.
$formtemplate = false
The template of the form created by sendAuthRequest().
Defaults to false (no template).
$usernamerules = array ()
A list of rules for the username form field. The keys are
the rules and the values are the invalid messages.
$passwordrules = array ()
A list of rules for the password form field. The keys are
the rules and the values are the invalid messages.
$formmessage = 'Please enter your username and password.'
The welcome message of the form. Defaults to
'Please enter your username and password.'
$invalidmessage = 'Sorry, the password you specified was invalid. Please try again.'
The invalid message of the form. Defaults to
'Sorry, the password you specified was invalid. Please try again.'
$timeoutmessage = 'Sorry, your session has timed out. Please sign in again to continue.'
The timeout message of the form. Defaults to
'Sorry, your session has timed out. Please sign in again to continue.'
$sessObj
A reference to the main session object, in case it's
needed by a specific handler.
$error = false
Contains the error message if any error occurs within
this class, the handler or the source drivers, or false if no
error has occurred.
$total
Number of users.
$dir = 'inc/conf/auth/roles'
Directory to store info.
$data = array ()
Parsed data from file.
$file = 'inc/conf/auth/resources/index.php'
File to store resource info.
$id
The session id value.
$valid = false
Says whether this session is valid.
$username
Contains the username of the user.
$password
Contains the password of the user.
$useID = true
Specifies whether or not to use a session id. Some handlers or
sources may not support session ids (ie. the Basic handler), and so they
may be disabled.
$timeout = 3600
Specifies a length in seconds that the session may be inactive
for before automatically logging the user out. This is also optional,
as some handlers or sources may not support it.
$autoSave = true
Specifies whether calls to set() should also call save()
automatically. Defaults to true, since for most intents and purposes
this is a nice way of not having to think about it.
$handler
The handler driver object.
$source
The source driver object.
$store
The store driver object.
Return to Top
Methods
Session ($handler, $sources, $store, $username, $password, $id = '')
Constructor method.
init ($path = 'inc/conf/auth')
Initializes the session objects, which is necessary to do outside of
the constructor because a constructor can't properly reference $this
inside of itself it seems.
setTimeout ($timeout)
Sets the value of the $timeout property.
setSourceProperties ($source, $properties)
Sets any custom properties of the source driver.
setHandlerProperties ($properties)
Sets any custom properties of the handler driver.
setStoreProperties ($properties)
Sets any custom properties of the store driver.
authorize ($user, $pass, $id = false)
- Access: public
- Return: boolean
Check the autorization of a user but do not log them in. Useful for
web services or external applications requiring authentication but
which should not log the person out on the website through their use.
start ()
- Access: public
- Return: boolean
Starts the session logic. This is typically the stage where
the username/password or session id will be verified, so after this
stage you will be able to check the $valid property to see if the
user is valid.
sendAuthRequest ()
- Access: public
- Return: boolean
This method issues a request for authorization to the visitor.
This request may be an HTTP WWW-Authenticate header, an HTML sign in
form, a SOAP message (providing you have a SOAP handler driver), or
just about any conceivable way of making this request.
gatherParameters ($handler, $sessionidname)
- Access: public
- Return: array
Retrieves the appropriate username, password, and session id
values from anywhere in the script, which are gathered through the
gatherParameters() method of the specified $handler, because the
handlers often know more about the environment than this class because
they must interact with the visitor.
makePendingKey ()
- Access: public
- Return: string
Creates a 32 character string of the form 'PENDING:' plus a 24
character long random string. Used for creating pending accounts.
close ()
Closes the session handler, source, and the store. Call this to
log a user out and terminate their session. Please note: when a session
is terminated, all data stored in it that is not written to a permanent
storage location is lost.
get ($name)
- Access: public
- Return: mixed
Retrieves a value from the session store. Returns false if
the value does not exist.
set ($name, $value = false)
- Access: public
- Return: mixed
Sets a value in the session store. If the value is false,
it will unset it in the store. If the value is being unset or
set to a new value, then the old value is returned. If it is a
new value, then the value itself will be returned. If $autoSave
is on, check $error if you want to make sure it worked.
append ($name, $value = false)
- Access: public
- Return: array
Sets an array value in the session store. If the array
is empty, it will create a new array. If the value is false, it
will empty the array. If $autoSave is on, check $error if you
want to make sure it worked. Returns the array prior to making
the change.
save ()
- Access: public
- Return: boolean
Tells the session store to save the values within it.
allowed ($resource = 'documents', $access = 'rw', $type = 'resource')
- Access: public
- Return: boolean
Specifies whether the user is allowed to access the requested
resource. $resource may be a string, or an object or associative array
with the properties name, sitellite_acces, and sitellite_status.
Valid $access values are r, w, and rw (read, write, and read/write).
Valid $type values are resource, access, and status.
allowedSql ()
- Access: public
- Return: string
Returns a piece of SQL that can be slipped into the WHERE clause of
a query to check for proper permissions.
makeRecoverKey ()
- Access: public
- Return: string
Creates a 32 character string of the form 'RECOVER:' plus a 24
character long random string. Used for recovering passwords.
isValidKey ($user, $key)
Checks the validity of the specified recovery key.
update ($data = array (), $user = false)
Updates the user's data in the data source. May update another user
than the current one by specifying a username as the second parameter.
getUser ($username = false)
Finds a user by their email address.
getUserByEmail ($email)
Finds a user by their email address.
&getManager ()
Retrieves a copy of the session manager object.
Return to Top