NAME

PHP::Session::DBI - Interface to PHP DataBase Sessions

SYNOPSIS

   use DBI;
   use PHP::Session::DBI;

   my $dbh = DBI->connect($DSN, $user, $password);
   my $opt = {
      db_handle => $dbh,
      db_table  => 'sessions',
      db_schema => {
         # session table schema for SMF
         id   => 'session_id',
         data => 'data',
         date => 'last_update',
      }
   };
   my $session = PHP::Session::DBI->new($sid, $opt);
   
   # the rest is regular PHP::Session interface
   
   # session id
   my $id = $session->id;
   
   # get/set session data
   my $foo = $session->get('foo');
   $session->set(bar => $bar);
   
   # remove session data
   $session->unregister('foo');
   
   # remove all session data
   $session->unset;
   
   # check if data is registered
   $session->is_registered('bar');
   
   # save session data
   $session->save;
   
   # destroy session
   $session->destroy;

DESCRIPTION

PHP::Session::DBI provides a way to read / write PHP database sessions, with which you can make your Perl application session shared with PHP. This module is a PHP::Session subclass, not a re-implementation of the whole interface.

METHODS

See PHP::Session for other methods and extra documentation.

new

Usage:

   my $session = PHP::Session->new($SID, $OPTIONS);

First parameter is the session ID. It can be fetched from a cookie or a get request. new takes some options as hashref as the second parameter. See PHP::Session for other options. This documentation only discusses PHP::Session::DBI related options.

db_handle

See "DATABASE SESSIONS".

db_table

See "DATABASE SESSIONS".

db_schema

See "DATABASE SESSIONS".

dbh

Returns the database handle.

DATABASE SESSIONS

PHP sessions can be stored in a RDBMS using session_set_save_handler() function. File sessions considered unsecure under shared environments. So, database sessions start to gain popularity. An example usage for database sessions can be the popular SMF (http://www.simplemachines.org) software. Note that, this module might not be compatible with some arbitrary session implementations.

You can enable three special options to new to access database sessions: db_handle, db_table and db_schema. But note that, you must first install DBI and the related DBD (i.e.: DBD::mysql for MySQL) to communicate with the database server.

db_handle

db_handle is the DBI database handle. PHP::Session::DBI currently does not implement a way to create it's own connection and it needs an already started connection and a database handle.

db_table

db_table is the table name of the sessions table.

db_schema

db_schema describes the session table structure to PHP::Session::DBI. Without db_schema, the module can not interface with the sessions table. db_schema is a hashref and includes some mandatory and optional keys.

You have to define different schemas for different software, since there is no standard in field names.

id

Mandatory. The name of the session id field in the table.

data

Mandatory. The name of the session data field in the table.

date

Mandatory. The name of the session date field in the table. This can be the last modified or timeout value or anything else.

update_date

Optional boolean value. If it is true, then the date field will be updated with time() if the session is modified.

But note that, the date field will get the initial value from time() if you are creating a new session.

EXAMPLE

   use DBI;
   use PHP::Session::DBI;
   use CGI qw(:standard);
   # database configuration
   my %CONFIG = (
      db_driver   => "mysql",
      db_user     => "root",
      db_password => "",
      db_host     => "localhost",
      db_port     => 3306,
      db_database => "mydatabase",
      db_table    => "sessions",
   );
   # DBI options
   my %DBI_ATTR = (
      RaiseError => 1,
      PrintError => 0,
      AutoCommit => 1,
   );
   # Data Source Name
   my $DSN = sprintf "DBI:%s:database=%s;host=%s;port=%s", 
                     @CONFIG{ qw/ db_driver db_database db_host db_port / };
   # database handle
   my $dbh = DBI->connect($DSN, @CONFIG{qw/ db_user db_password /}, \%DBI_ATTR);
   # get the session id from cookie
   my $SID     = cookie('PHPSESSID');
   # fetch the session
   my $session = PHP::Session::DBI->new(
                    $SID,
                    {
                       db_handle => $dbh,
                       db_table  => $CONFIG{db_table},
                       db_schema => {
                          id   => 'session_id',
                          data => 'data',
                          date => 'last_update',
                       },
                       auto_save => 1,
                    }
                 );
   #create a new session key
   $session->set(burak => "TESTING ... ");

SEE ALSO

PHP::Session, http://tr.php.net/session_set_save_handler, http://www.raditha.com/php/session.php and http://www.simplemachines.org.

There is a similar module called PHP::Session::DB. However, it does not meet my requirements and especially, the SQL statements are hard-coded with weird field names, which makes it impossible to use in different systems.

AUTHOR

Burak Gürsoy <burak@cpan.org>

COPYRIGHT

Copyright 2007 Burak Gürsoy. All rights reserved.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.