TracNav menu
Getting Started
This document tries to kick-start you into your first application using patSession. Of course, I know, your intention is to get your application up and running. You definitely don't want to bother about sessions handling.
Ready - Steady - Go!
As you might have guessed, patSession hides the PHP session functions behind an OO-API. So, instead of using start_session() you now use the patSession factory method patSession::singleton() to start the session and recieve a reference to the current session object.
// patSession requires patError! require_once 'pat/patErrorManager.php'; // include the factory/load of patSession require_once 'pat/patSession.php'; // start the session $sess = patSession::singleton( 'my_first_session' ); echo '<b>class name:</b> ' . get_class( $sess ) . '<br />';
The example above also shows how to use created session object. But for sure you want to store something into the session and restore it later. An very PHPish way doing this is accessing the session object as if it was an array. The following example shows how to put "Jack" in the "box" and "foo" into "bar"
// start the session $sess = patSession::singleton( 'my_first_session' ); $sess['box'] = 'Jack'; $sess['bar'] = 'foo';
Later on you might want to recover Jack from the box
echo 'Look! There is ' . $sess['box'] ' in the box<br />';
Instead of unsing the fancy array access interface you can use old-school getter and setter methods
$sess->set( 'box', 'jack' ); echo 'Look! There is ' . $sess->get( 'box' ) ' in the box<br />';
Of course, besides simple scalar data, you can store arrays and objects in the session. This is what most of users do with session, still, patSession does more.
SID things
Session sipport in web usually means putting the current session id in HTML(?) output. To make this process a bit more comfy PHP uses the constant SID, patSession provides the same information in a more OO manner - using the read-only member variable: SID:
echo '<a href="index.php?' . $sess->SID . '">home</a>';
Besides the SID emulation, there are more read-only member variables that reveal useful information for curious developer.
echo 'The current session id ' . $sess->id . '<br />';
echo 'The current session name ' . $sess->name . '<br />';
echo $sess->state . ' lets you know whether the running session is healthy<br />';
echo 'Some prefer session ids with a custom prefix ' . $sess->idPrefix . '<br />';
if( $sess->new ) {
echo 'This session is brand new<br />';
} else {
echo 'This session was called ' . $sess->counter . ' times/requests<br />';
echo '<pre>' . print_r( $sess->counter, true ) . '</pre><br />';
}
Getting Started
This document referes to the examples in the patSession download package. Therefore it is recommended to test and play with the "real source" beforeyou start using patSession.
Ready - Steady - Go!
As you already know, patSession hides the php session functions behind an OO-API. So, instead of using start_session() you now use the patSession factory method patSession::singleton() to start the session and recieve a reference to the current session object.
<?PHP // patSession requires patError! require_once 'pat/patErrorManager.php'; // include the factory/load of patSession require_once 'pat/patSession.php'; // start the session $sess = patSession::singleton( 'my_first_session' ); echo '<b>class name:</b> ' . get_class( $sess ) . '<br />'; // store a value $sess->set( 'fb', 'fine business' ); // recover a value from the session $fb = $sess->get( 'fb' ); echo '<b>fb:</b> "'. $fb .'"<br />'; // Recieve session-query-string, // use this as an replacement of the PHP-constant "SID" echo '<b>SID replacement</b>' . $sess->SID . '<br />'; ?>
The example above also shows how to use created session object. The most common used methods are get to recieve a named value from the session and set to store any named value in the session.
Furthermore the session object also provides some methods to gain some information about the current session. For example getQueryString returns a string that can be used like the PHP constant SID (see PHP-manual, chapter Session Handling Functions)
Factory Method
The patSession factory provides two methods for instanciating session objects: create and singleton.
If you are familiar with programming patterns, you will already know how to use both factory methods. Using patSession::singleton() will only create <em>a single instance</em> of the patSession-Storage object. In other words, this method will always return a reference to the same object, even if you use different arguments.
<?PHP
require_once 'pat/patErrorManager.php';
require_once 'pat/patSession.php';
$sess1 = patSession::singleton( 'my_first_session' );
$sess2 = patSession::singleton( 'my_first_session' );
if( $sess1 === $sess2 )
{
echo 'Session 1 and 2 are references'
. ' to a single instance.<br />';
}
// try with different arguments!
$sess3 = patSession::singleton( 'not_my_first_session' );
if( $sess1 === $sess3 )
{
echo 'Session 1 and 3 are references'
. ' to the same instance, too.<br />';
}
?>
Using the singleton-method is a very handy way to make sure that you alway refer to the same instance. As most applications only need a single storage container to keep track of the user's session, this is the recommended way of creating session objects.
Another benefit of the patSession::singleton() is, that you may use it wherever you need a refernece to the current session. This feature makes it very easy to integrate patSession in your own classes without juggling references from one object to another.
On the other side there is the factory method patSession::create(). This class-function behaves similar to the singleton-function, but allows you to run multiple, independent session-objects at the same time.
At this point, the first parameter, the <em>session name</em> is important. Internaly the patSession-factory keeps track of the created instances by associating them to their names. As long as the name-parameter of the create-method referes to an already instanciated object, it will return a reference to the existing instance. Otherwise a new instance will be created and stored associated to its name.
<?PHP
require_once 'pat/patErrorManager.php';
require_once 'pat/patSession.php';
$sess1 = patSession::create( 'my_first_session' );
$sess2 = patSession::create( 'my_first_session' );
if( $sess1 === $sess2 )
{
echo 'Session 1 and 2 are references'
. ' to a single instance.<br />';
}
// try with different name!
$sess3 = patSession::create( 'mot_my_first_session' );
if( $sess1 !== $sess3 )
{
echo 'Session 1 and 3 are '
. ' independent instance.<br />';
}
// try with different arguments!
$sess4 = patSession::create( 'my_first_session', 'Native', array( 'expire' => 10 ) );
if( $sess1 !== $sess4 )
{
echo 'Session 1 and 4 are references'
. ' to a single instance.<br />';
}
?>
In the example above, $sess1 and $sess2 are the same, because the first parameter of patSession::create() are the same. As mentioned above, this parameter is the name of the session.
$sess1 and $sess3 are independent - those are sessions with different names.
$sess1 and $sess4 refer to the same instance again. Even if the argument list differs, the session name is still the same.
Factory Parameter
As the previous example showd, the patSession-factory methods uses parameter to configure the created objects. patSession::singleton() accepts three parameter:
Container Methods
Once you have instanciated a patSession storage container, you mainly will use it to store and restore values in and from the session. Therefore the methods get and set are good for (see the first example). But, there is is more:
The most important feature is to manipulate variables stored in a session. See the following example how patSession handles the values stored in the session containers.
<?PHP
require_once 'pat/patErrorManager.php';
require_once 'pat/patSession.php';
// control session variables
$sess = patSession::create( 'my_first_session' );
echo '<pre>';
// try to recieve an non-existing variable
$unused = $sess->get( 'unused' );
echo 'this was never used before: ';
var_dump( $unused );
// or use ArrayAccess
if( isset( $sess['unused'] ) ) {
echo 'unused ' . $sess['unused'] . ' is used! ' . "\n";
}
// store and get
$sess->set( 'myvar', 42 );
$my = $sess->get( 'myvar' );
echo 'myvar: ';
var_dump( $my );
// again use ArrayAccess
$sess['myvar'] = 42;
echo 'myvar: ';
var_dump( $sess['myvar] );
// clear
$sess->clear( 'myvar' );
$my = $sess->get( 'myvar' );
echo 'myvar: ';
var_dump( $my );
// again use ArrayAccess
unset( $sess['myvar'] );
echo '</pre>';
?>
In the next example you can see, how to recieve the session name and id. Those information are essential to pass the session as get or post parameter to the next request.
<?PHP require_once 'pat/patErrorManager.php'; require_once 'pat/patSession.php'; $sess = patSession::create( 'my_first_session' ); // replacement for SID echo '<b>SID replacement:</b> ' . $sess->SID . '<br />'; // session name echo '<b>Session Name:</b> ' . $sess->getName() . '<br />'; // session id echo '<b>Session Id:</b> ' . $sess->getId() . '<br />'; ?>
To support secure session handling, patSession provides some options for example to expire idle sessions and also some methods.
<?PHP
require_once 'pat/patErrorManager.php';
require_once 'pat/patSession.php';
$sess = patSession::create( 'my_first_session' );
// see whether the session is active
$state = $sess->getState();
// clone the session for example after successful user login
$result = $sess->fork();
if( patErrorManager::isError( $result ) ) {
die( 'forking session failed' );
}
// kill session and empty storage container
$result = $sess->destroy();
if( patErrorManager::isError( $result ) ) {
die( 'cannot destroy session' );
}
?>
