YaBB3::Entities::Session - The YaBB3 Session Object


Name

YaBB3::Entities::Session - The YaBB3 Session Object


Synopsis

  use YaBB3::Entities::Session
  # Create a guest session object.
  $session = YaBB3::Entities::Session->startGuest();
  # Create a member session object.
  my $newvalues = {};
  $newvalues->{uid}      = $uid;
  $newvalues->{ip}       = $ip
  $newvalues->{started}  = $timeStarted;
  $newvalues->{updated}  = $timeLastUpdated;
  $newvalues->{location} = $queryComponent;
    
  my $session = new YaBB3::Entities::Session;
  my $sid = $session->create($newvalues);
  my $user = $session->loadUser();
  ====================
  # Class methods.
  $session  = YaBB3::Entities::Session->getSessionByIP($ip);
  $sid      = YaBB3::Entities::Session->generateKey();
  $sessions = YaBB3::Entities::Session->loadOnline({LOAD_USERS => 1, TIMEOUT => 1200});
  $count    = YaBB3::Entities::Session->countOnlineGuests(1200);
  $sessions = YaBB3::Entities::Session->loadTimedOut({LOAD_USERS => 1});
  $result   = YaBB3::Entities::Session->pruneTimedOut();
  $count    = YaBB3::Entities::Session->count({Where => $whereClause});
  $sessions = YaBB3::Entities::Session->loadList($whereClause);
  # Object methods.
  $user     = $session->loadUser();
  $exists   = $session->checkExists();
  $result   = $session->create();
  $result   = $session->loadData();
  $result   = $session->storeData();
  $result   = $session->delete();
  $result   = $session->isValid();
  $result   = $session->update();


Overview

An object that represents a database backed session record. The session record stores the login context between queries and is identified by a unique session id string.


Description

The Session class is a sub-class of the YaBB3::Base database record class. It represents a record in the session table of a forum database.

A session is used to preserve the context of a single user between queries. When created, a unique session id is generated and returned to the user in the form of a query component in link URLs, or in a cookie. The next query from that same user can get the session id from these sources (URL or cookie) and process the query in the context of that user.

A user not logged in as a registered member is automatically given a guest session. When a user logs-in as a registered member, their guest session is replaced by a user session. When they log-out, the user session is replaced by a guest session.

Object Creation

You create a new user session in the manner defined by the YaBB3::Base super-class:

  1. Create a new Session object with the new method.

  2. Fill the newvalue hash with the record fields.

  3. Create the session table record with the create method.

  4. Merge the newvalues hash with the values hash with the mergeValues method, and clear the newvalues hash.

The YaBB3::Entities::User object matching the session uid can be loaded with the loadUser method.

To generate a unique session id, use the generateKey method and pass 'VERIFY_KEY => 1' in the parameter hash arguement.

To create a guest session, you can use the startGuest convenience method. It will automaically generate a unique session id, fill the record fields, create the record, and return the updated session object.

A session can be deleted from the backing database with the the delete manpage method.

The Session Record.

Each of the record fields can be read from the values object field hash. The record fields are updated from the database record by calling the loadData method.

The record fields can be set by assigning each record field and new value to the newvalues object field hash, calling the storeData method, merging the newvalues hash into the values hash with the mergeValues method, and clearing the newvalues hash.

You can check if a Session record with the same session id already exists in the backing database with the checkExists method.

The Session Table

A variety of class methods are provided that perform searching, listing, and counting functions on the entire session table in the backing database.

getSessionByIP
Creates a Session object for the first session record found with an ip record field that matches the given IP address.

loadList
Returns an array of Session objects for each session record that matches a given SELECT database command WHERE clause.

loadOnline
Returns an array of Session objects for each session record that has been updated during a timeout period.

loadTimedOut
Returns an array of Session objects for each session record that has not been updated during a timeout period.

count
Returns a count of session records that matches a given SELECT database command WHERE clause.

countOnlineGuests
Returns a count of guests session records that have not timed-out.

pruneTimedOut
Deletes from the session table all session records that have timed-out.


Reference

Use Packages

  YaBB3::Base  $Y
  YaBB3::Entities::User

Package Fields

  $VERSION  The package version number as a float.

Object Super Classes

  YaBB3::Base

Public Class Methods

startGuest

  Returns
  /%       The new guest session object.
  undef    An error was logged.

Create and return a new session object with a guest account login.

getSessionByIP

  $myip    The IP address.
  Returns
  /%       The first matching session object.
  undef    No matching session found, or an error was logged.

Get the first session that has the given IP address.

generateKey

  /%config  [Opt] Configuration parameters.
              COUNT      => The key character count
              VERIFY_KEY => True - Verify the key does not exist in the database
  Returns
  $         The generated session key.

Generates and returns a session key. The key character length and uniqueness can be configured.

verifyKey

  $key     The key to test
  Returns
  $        1  If the key is not found in the database
  $        0  If the key is found in the database
  undef    An error was logged.

Returns true if the given key is not already in the forum database.

loadOnline

  /%config  [Opt] Loading configuration parameters.
              LOAD_USERS => True - Also loads the users for each session
              TIMEOUT    => Inactivity timeout in seconds (default: 1200s)
  Returns
  /@        A reference to an array of Session object references.
  undef     An error was logged.

Loads the current list of online sessions. A running session is considered online if it has been updated within a timeout (default: 1200s). Optionally loads the user of each session.

countOnlineGuests

  $timeout  [Opt] The online timeout in seconds (default: 1200s).
  Returns
  $         The count of online guests.
  undef     An error was logged.

Returns a count of online guest sessions. A session is considered online if it has been updated within a timeout (default: 1200s).

loadTimedOut

  /%config  Configuration parameters.
            LOAD_USERS => True - Also loads the user for each session
  Returns
  /@        A reference to an array of Session object references.
  undef     An error was logged.

Loads the list of timed-out sessions. Optionally loads the user for each session.

pruneTimedOut

  Returns
  $        1
  undef    An error was logged.

Deletes all timed-out sessions.

loadList

loadList $where [Opt] The WHERE clause of the session table select. Returns /@ A reference to an array of Session object references (undef if none). undef No sessions returned, or an error was logged.

Load a list of all sessions that satisfy the given WHERE clause.

count

  /%config  [Opt] Configuration parameters.
              WHERE  The WHERE clause for the database select command.
  Returns
  $         The session count.
  undef     An error was logged.

Returns a count of sessions that satisfy the given WHERE clause.

Object Fields

\%user
The session's YaBB3::Entities::User object.

Record Fields

$sid
The session id.

uid
The id of this session's user.

$uid
The id of this session's user.

$started
The time this session was started.

$updated
The time this session was last updated.

$location
The query string component for this session.

$referrer
The URL of the referring page.

$ip
The IP address of this session's user.

Public Object Methods

loadUser

  Returns
  /%       A reference to a YaBB3::Entities::User object.
  undef    An error was logged.

Load the user for this session.

update

  Returns
  undef    An error was logged.

Update the session in the database with uptodate data

checkExists

  Returns
  $        1 This session ID exists
           0 This session ID does not exist

Return true if this session ID exists in the forum database.

isValid

  Returns
  $        1 This session is valid
           0 This session is invalid

Return true if this session is valid.

create

  Returns
  $        1
  undef    An error was logged.

Create a new session in the forum database with the fields contained in the newvalues field. This does not create or return a new Session object.

loadData

  Returns
  $        1
  undef    An error was logged.

Load the values field with the fields from this session in the forum database.

storeData

  Returns
  $        1
  undef    An error was logged.

Update this session's fields in the forum database with the values from the newvalues field.

delete

  Returns
  $        1
  undef    An error was logged.

Deletes this session from the forum database.


AUTHOR

Copyright ©2002, YaBB 3 Development Team. All Rights Reserved.
You may distribute this module under the terms of YaBB 3.
 YaBB3::Entities::Session - The YaBB3 Session Object