Embperl - building dynamic websites with Perl

• Functions/Methods for session handling
• Embperl::Req::SetupSession ($req_rec, $uid, $sid, $app_param) [1.3b6+]
• Embperl::Req::GetSession / $r -> GetSession [1.3b6+]
• Embperl::Req::CleanupSession ($req_rec, $app_param) [1.3b6+]
• Embperl::Req::DeleteSession / $r -> DeleteSession [1.3b6+]
• Embperl::Req::RefreshSession / $r -> RefreshSession [1.3b6+]
• Embperl::Req::SetSessionCookie ($req_rec, $app_param) [1.3b7+]

From 1.2b1 and higher Embperl is able to handle per user sessions for you. You can store any data in the %udat hash and if the same user requests an Embperl document again, you will see the same values in that hash again.

From 1.2b2 and higher Embperl is able to handle per module/page persistent data for you. You can store any data in the %mdat hash and if any request comes to the same Embperl document, you will see the same values in that hash again.

Session handling has changed from 1.3.3 to 1.3.4 and 2.0b3 to 2.0b4. You must either install Apache::SessionX or set

    PerlSetEnv EMBPERL_SESSION_HANDLER_CLASS "Embperl::Session"

to get the old behaviour. If you have Apache::SessionX installed, you don't have to make additional configuration, otherwise you must do the following things. You are also able to override the Apache::SessionX defaults, by using the following parameters:

To configure Embperl to do session management for you, you must have installed Apache::Session (1.53 or higher) and tell Embperl which storage and locker classes you would like to use for Apache::Session. This is done by setting the environment variable EMBPERL_SESSION_CLASSES. If you want to use a MySQL database for storing your sessions, you may have a startup.pl for your httpd which looks like this:

 BEGIN
    {
    $ENV{EMBPERL_SESSION_CLASSES} = "MySQL Semaphore" ;
    $ENV{EMBPERL_SESSION_ARGS}    = "DataSource=dbi:mysql:session UserName=test" ;
    } ;

 use Embperl ;

or you may put this in the httpd/srm.conf:

 PerlSetEnv EMBPERL_SESSION_CLASSES "MySQL Semaphore"
 PerlSetEnv EMBPERL_SESSION_ARGS "DataSource=dbi:mysql:session UserName=test"
 PerlModule Embperl ;

Refer to the Apache::Session docs (e.g. Apache::Session::Store::MySQL) on how to setup your database tables.

EMBPERL_SESSION_ARGS is a space separated list of name/value pairs, which gives additional arguments for Apache::Session classes.

Here is an example for using a filesystem based storage:

PerlSetEnv EMBPERL_SESSION_CLASSES "File Semaphore" PerlSetEnv EMBPERL_SESSION_ARGS "Directory=/path/to/your/sessions"

Refer to the Apache::Session docs to find out which other storage/locker methods are available.

EMBPERL_SESSION_CLASSES can (optionally) take two more classnames, which specify the class for serialization (Default: Storable) and for generating the id (Default: MD5).

NOTE: The above configuration works only with Apache::Session 1.52 and Embperl 1.3b5 or above. Older versions of Embperl only support Apache::Session 1.0x, which has different parameters for EMBPERL_SESSION_CLASSES (e.g. $ENV{EMBPERL_SESSION_CLASSES} = "DBIStore SysVSemaphoreLocker" ; ) Apache::Session 1.0x still works with this Embperl version.

Now you are able to use the %udat and %mdat hashes for your user/module sessions. As long as you don't touch %udat or %mdat, Embperl will not create any session, and Apache::Session is not loaded. As soon as you store any value to %udat, Embperl will create a new session and send a cookie to the browser to maintain its id, while the data is stored by Apache::Session. (Further version may also be able to use URL rewriting for storing the id). When you modify %mdat, Embperl will store the data via Apache::Session and retrieve it when the next request comes to the same page.

This can be used from a script that will later call Embperl::Execute to preset the session so it's available to the calling script.

	$req_rec
	Apache request record when running under mod_perl, undef otherwise.
	$uid
	Session ID of the user session. If not given it is taken from the session cookie or out of the query_string.
	$sid
	Session ID of the state session. If not given it is taken out of the query_string.
	$app_param
	SetupSession tries to figure out the correct Application object for this request, in case this is not possible you can pass parameters for the Application object as a hash ref. To pass the name of the application object to use, try to pass: { appname => 'myappname' }

Returns a reference to %udat or, if call in an array context, a reference to %udat %mdat and %sdat. See also CleanupSession.

Returns a reference to %udat or, if called in an array context, a reference to %udat and %mdat. This could be used by modules that are called from inside an Embperl page, where the session management is already setup. If called as a method $r must be a Embperl::Req object, which is passed as first parameter to every Embperl page in @_ .

Must be called at the end of a script by scripts that use SetupSession, but do not call Embperl::Execute.

	$req_rec
	Apache request record when running under mod_perl, undef otherwise.
	$app_param
	CleanupSession tries to figure out the correct Application object for this request, in case this is not possible you can pass parameters for the Application object as a hash ref. To pass the name of the application object to use, try to pass: { appname => 'myappname' }

Deletes the session data and removes the cookie from the browser. If called as a method $r must be a Embperl::Req object, which is passed as first parameter to every Embperl page in @_ .

Triggers a resend of the cookie. Normally the cookie is only sent the first time. If called as a method $r must be a Embperl::Req object, which is passed as first parameter to every Embperl page in @_ .

Must be called by scripts that use SetupSession, but do not call Embperl::Execute. This is necessary to set the cookie for the user session id, in case a new session is created, which is normally done by Embperl::Execute.

SetSessionCookie does only set the cookie for the user session and it works only when running under mod_perl. It does not set session id if no cookies are used. Also it does not care about the state session.

	$req_rec
	Apache request record when running under mod_perl, undef otherwise.
	$app_param
	SetupSessionCookie tries to figure out the correct Application object for this request, in case this is not possible you can pass parameters for the Application object as a hash ref. To pass the name of the application object to use, try to pass: { appname => 'myappname' }