[cgiapp] RFC: DBI::Session proposed docs

[Mark Stosberg <suppressed>]

Hello all,

Thanks for the conversation about session handling. I've learned a lot. 

Below is the proposed interface for the new database-centric session
module I'm proposing. I haven't addressed serialization in the
interface.  What would serialization fans think about having it be
external? Maybe like this:

  $ses->param( 'all' => freeze($q) );
   my $q = thaw( $ses->param('all') );

Too much of a pain? Proposals welcome. 

I also haven't mocked up here, but like CGI::Session, this module could
be easy to use with a simple CGI::App plugin. In fact for database
backends it can be even easier, because it can take the connection from
$self->dbh(). 

As a design goal, no database driver layer should be needed. 

I also want to explain why I removed a few CGI::Session methods:

 clear(@list)  | update() can be used instead, but this syntactic sugar could be added back.
 clear()       | 
 expire()      | Use update( duration => '' ) instead. 
                 Compatibility for CGI.pm cookie style could be ripped from CGI::Session.
                 Again, this method could re-appear as syntactic sugar.
 
 close()       | Can't we just let it go out of scope or abandon it? 
               | Could be added later anyway. 
 
 error         | Not needed, but could be emulated with eval() and suppressed
 dump          | Not needed, but could be emulated easily              

##########################################

So, given everything we've discussed, does it seem worth it to you to
have yet-another session handling module, or are you happy enough with
CGI::Session? 

    Mark

##########################################

NAME
    DBI::Session - Database-driven session management

SYNOPSIS
        use DBI::Session;
        my $ses = DBI::Session->new( dbh=> $dbh );

        # getting the effective session id 
        my $CGISESSID = $ses->id(); 
    
        # storing data in the session
        $ses->param('first_name' =>  'George');

        # retrieving data
        my $f_name = $ses->param('first_name');

        # clearing a certain session parameter
        $ses->param( "_IS_LOGGED_IN" => undef );

        # expire '_IS_LOGGED_IN' flag after 10 idle minutes:
        $ses->param('_IS_LOGGED_IN_exp => '10 min');

        # expire the session itself after 1 idle hour
        $ses->param('duration' => '1 hour');

        # delete the session for good
        $ses->delete();

METHODS
  new()
     my $u = DBI::Session->new(
            dbh            => $dbh, 
            query      => $q, # defaults to CGI->new(),
            ses_table  => 'uploads', # defaults to "sessions"

        id_gen     => \&callback, # defaults to MD5 hash
     );

    dbh [required]
        DBI database handle. Required.

    query.
        A CGI.pm-compatible object, used to automatically initialize the
        session when no session ID is provided.

    ses_table
        Name of the SQL table where sessions are stored. See example syntax
        above or one of the creation scripts included in the distribution.
        Defaults to "sessions" if omitted.

    ses_table_map
        A hash reference which defines a mapping between the column names
        used in your SQL table, and those that DBI::Session uses. The keys
        are the DBI::Session default names. Values are the names that are
        actually used in your table.

        This is not required. It simply allows you to use custom column
        names.

          session_id             => 'session_id',
          remote_addr        => 'remote_addr',  
          creation_time      => 'creation_time',
          last_access_time   => 'last_access_time', 
          duration                   => 'duration', 

        You may also define additional column names with a value of 'undef'.

        For any additional columns you add, if you would like to expire that
        column individually, you need to an additional column to do that.
        For example, to add a column named "order_id" which you want to
        allow to be expired, you would add these two columns:

                order_id                        int,
                order_id_exp        interval,

    id_gen
        A callback for generating session_ids. It defaults to generating MD5
        encoded hexidecimal random ids. Here's an example of a callback,
        using the default code.

            id_gen     => sub { 
                require Digest::MD5;
                my $md5 = new Digest::MD5();
                $md5->add($$ , time() , rand(9999) );
                return $md5->hexdigest();
            }

  id()
    Returns effective ID for a session. Since effective ID and claimed ID
    can differ, valid session id should always be retrieved using this
    method.

  delete()
    deletes the session from the disk. In other words, it calls for
    immediate expiration after which the session will not be accessible

  last_access_time()
    returns the last access time of the session as a DateTime object. This
    time is used internally while auto-expiring sessions and/or session
    parameters.

  creation_time()
    returns the time when the session was first created as a DateTime
    object.

  remote_addr()
    returns remote IP address of session user

  param($name)
  param($name,$value)
    A vanilla param() method.

    With no arguments, returns a list of session parameter names.

    With one argument, Returns a session parameter set to $name or undef on
    failure.

    With two arguments, sets session $name parameter to $value.



    Mark

-- 
http://mark.stosberg.com/ 


---------------------------------------------------------------------
Web Archive:  http://www.mail-archive.com/suppressed/
              http://marc.theaimsgroup.com/?l=cgiapp&r=1&w=2
To unsubscribe, e-mail: suppressed
For additional commands, e-mail: suppressed