SessionsG2

Overview

Geeklog 2 has a completely revamped method for handling sessions. We will make use of the built-in session support in PHP but we will do so through the use of PEAR::HTTP_Session2. HTTP_Session2 provides an object-oriented interface into the built-in PHP session functions and it enhances functionality by allow us to store session in a database (by default, PHP stores session data in files). Geeklog 2 will default to storing session data in the database but user's can override this by changing the session related methods in the Geeklog 2 configuration file.

Benefits

For those coming from the 1.3.x codebase, you'll remember that all 1.3.x did was associate session ID's to user ID's. There was no way to persist data with the session across requests. Using HTTP_Session2, you can now add arbitrary information related to the user to their session and have that data available across requests. This is in stark contrast with the 1.3.x code that had to explicitly query different tables in the database to get information about the user. The the single greatest benefit to this new method for session handling is that we don't have to explicitly issue SQL to save session data...we just simply set a value on the $_SESSION superglobal and go about our way. I'll give some sample code to show how this works

Ground Rules

Because we now load session data for users into memory, this is a real concern about being able to quickly exhaust memory if we don't manage our sessions properly That being said there are a few ground rules you must adhere to:

1. Never put the Gl2User object in session. The Geeklog 2 Kernel will do that for you and put the user object in $_SESSION['user'].
2. Never access the $_SESSION['user'] object directly. The BaseViewUser and BaseCommandUser both have a user attribute that is linked to the user object. You access it by using $this->user
3. Don't put large amounts of data in the session. This is more of a guideline than anything but the key point is that the more data in a user session, the more RAM we use. Obviously we want to minimize that.
4. Clean up after yourself. If you put some data in the user session, be sure to clear it out when you no longer need it.
5. Be careful with objects. When you try to access objects in the session, you must ensure the class has been included via include/require or their _once derivatives. If you don't, you will get errors to the extent that the object doesn't exist. Also, be sure to never put Resources (e.g. database connections, LDAP connections, file pointers, etc) in the session as they won't work.

Example Code

The following code (which may be out of date, see CVS for sure) comes from /path/to/Geeklog-2/public_html/index.php and it initializes the session:

// Start a PHP-based session
try {
    HTTP_Session2::setContainer($glConf['session_container'],$glConf['session_creole_options']);
    HTTP_Session2::useCookies($glConf['session_use_cookies']);
    HTTP_Session2::start($glConf['session_name']);
} catch (Exception $e) {
    handleException($e);
}

This code shows how to put a variable into the session:

$_SESSION['application_name'] = 'Geeklog';

This code shows how to read a variable out of the session:

print $_SESSION['application_name'];

Finally, here's a more real world example. This is from Geeklog_DefaultAccountManager and shows how logging in happens and how the user object is then loaded into the session:

// Get the user object
$retval = $dao->find('getUserByUserName', array($_POST['username']));
if ($user->getPassword() <> $_POST['password']) {
    // Bad password, bail
    $logger->log('Invalid password for user, ' . $_POST['username']);
    $_REQUEST[MVC_ERRORS][] = 'Invalid username or password';
    return 'backToLogin';
}
$user = $retval[0];
$_SESSION['user'] = serialize($user);