View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Domizio Demichelis > CGI-Builder-Session-1.26 > CGI::Builder::Session



Annotate this POD

View/Report Bugs
Module Version: 1.26   Source  


CGI::Builder::Session - CGI::Builder and CGI::Session integration

VERSION 1.26 ^

The latest versions changes are reported in the Changes file in this distribution. To have the complete list of all the extensions of the CBF, see "Extensions List" in CGI::Builder


    CGI::Builder >= 1.2
    CGI::Session >= 3.95
    File::Spec   >  0
    perl -MCPAN -e 'install CGI::Builder::Session'

You have also the possibility to use the Bundle to install all the extensions and prerequisites of the CBF in just one step. Please, notice that the Bundle will install A LOT of modules that you might not need, so use it specially if you want to extensively try the CBF.

    perl -MCPAN -e 'install Bundle::CGI::Builder::Complete'
Standard installation

From the directory where this file is located, type:

    perl Makefile.PL
    make test
    make install


    use CGI::Builder
    qw| CGI::Builder::Session


Note: You should know CGI::Builder.

This module transparently integrates CGI::Builder and CGI::Session in a very handy and flexible framework that can save you some coding. It provides you a mostly automatic and ready to use CGI::Session object (cs property) useful to maintain the state of your application between requests. Please refer to CGI::Session for more documentation about sessions.

How it works

This extension creates a CGI::Session object automatically, using the old session id if it is found as a cookie or as a query param. If no session id is found, it creates a new session and automatically adds a session id cookie and a session id param that will be automatically used to send the id to the client

In simple cases you can avoid to init, update and flush the session: just use it and it will work as expected; if you need more customization you can override every single argument, property or even method.

Note: When you include in your CBB the CGI::Builde::Magic extension, you will have magically available a label that will be substituted with the current session id.


This module adds some session properties (all those prefixed with 'cs_') to the standard CBF properties. The default of these properties are usually smart enough to do the right job for you, but you can fine-tune the behaviour of your CBB by setting them to the value you need.


This property returns the internal CGI::Session object that is automatically created just before you use it. It is already initialized with the existing session or with a new session if there are no existing session yet. Anyway, you can directly use it in your code without any other initialization.

    # check some flag
    sub OH_pre_process {
        my $s = shift;
           || switch_to('login');

    # saves cgi parameter for later use
    sub PH_myPage1 {
        my $s = shift;
        $s->cs->save_param($s->cgi, "category");

    # retrieve a session parameter saved in a previous request
    sub PH_myPage2 {
        my $s = shift;
        my $categ = $s->cs->param("category");

Note: You can change the default arguments that are internally used to create the object by using the cs_new_args group accessor, or you can completely override the creation of the internal object by overriding the cs_new() method.

cs_new_args( arguments )

This property group accessor handles the CGI::Session constructor arguments that are used in the creation of the internal CGI::Session object. Use it to change the argument you need to the creation of the new object. Note: use it BEFORE using the cs object or your arguments will be ignored.

It uses the following defaults:

These defaults produce the most compatible and multiplatform CGI::Session object which is equal to:

    CGI::Session->new( undef,    # DNS equal to File
                       $s->cgi , # SID equal to cookie or param $CGI::Session::NAME
                       { Directory => File::Spec->tmpdir } # DSN_param for File

Note: You should change just the argument that you need to customize, i.e. usually just DSN and DSN_param and maybe new_session_init:

   $s->cs_new_args( DSN => .... ,
                    DSN_param => .... ,
                    new_session_init => sub{ ... },



This method is not intended to be used directly in your CBB. It is used internally to initialize and return the CGI::Session object. You usually don't need even to override it since you can customize the cs object by using the cs_new_args group accessor, or eventually override the cs_init method.


This method is internally called by the cs_new() method, so you don't need to know about it unless you need to override it. The purpose of this method is adding the session id cookie to the headers. Besides it adds also the session id query param to the query. (Note: those operations are done only if the session is new and using the $CGI::Session::NAME as the name of the cookie and query param, so you can set that variable as usual to set a different session id name.)

You should override this method only if you need to pass the new session id by any other mean (in this case you should also accordingly update the 'SID' argument of the cs_new_args).

Overriding Note: At the moment this method is executed, the cs property is not set yet, but the CGI::Session object is already created and available as $_[1].


See "SUPPORT" in CGI::Builder.


© 2004 by Domizio Demichelis (

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as perl itself.

syntax highlighting: