Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CGI::Application::PlugUserSContributed PerCGI::Application::Plugin::Session(3)

NAME
       CGI::Application::Plugin::Session - Plugin that adds session support to
       CGI::Application

VERSION
       version 1.05

SYNOPSIS
	use CGI::Application::Plugin::Session;

	my $language = $self->session->param('language');

DESCRIPTION
       CGI::Application::Plugin::Session seamlessly adds session support to
       your CGI::Application modules by	providing a CGI::Session object	that
       is accessible from anywhere in the application.

       Lazy loading is used to prevent expensive file system or	database calls
       from being made if the session is not needed during this	request.  In
       other words, the	Session	object is not created until it is actually
       needed.	Also, the Session object will act as a singleton by always
       returning the same Session object for the duration of the request.

       This module aims	to be as simple	and non	obtrusive as possible.	By not
       requiring any changes to	the inheritance	tree of	your modules, it can
       be easily added to existing applications.  Think	of it as a plugin
       module that adds	a couple of new	methods	directly into the
       CGI::Application	namespace simply by loading the	module.

NAME
       CGI::Application::Plugin::Session - Add CGI::Session support to
       CGI::Application

METHODS
   session
       This method will	return the current CGI::Session	object.	 The
       CGI::Session object is created on the first call	to this	method,	and
       any subsequent calls will return	the same object.  This effectively
       creates a singleton session object for the duration of the request.
       CGI::Session will look for a cookie or param containing the session ID,
       and create a new	session	if none	is found.  If "session_config" has not
       been called before the first call to "session", then it will choose
       some sane defaults to create the	session	object.

	 # retrieve the	session	object
	 my $session = $self->session;

	 - or -

	 # use the session object directly
	 my $language =	$self->session->param('language');

   session_config
       This method can be used to customize the	functionality of the
       CGI::Application::Plugin::Session module.  Calling this method does not
       mean that a new session object will be immediately created.  The
       session object will not be created until	the first call to
       $self->session.	This 'lazy loading' can	prevent	expensive file system
       or database calls from being made if the	session	is not needed during
       this request.

       The recommended place to	call "session_config" is in the	"cgiapp_init"
       stage of	CGI::Application.  If this method is called after the session
       object has already been accessed, then it will die with an error
       message.

       If this method is not called at all then	a reasonable set of defaults
       will be used (the exact default values are defined below).

       The following parameters	are accepted:

       CGI_SESSION_OPTIONS
	   This	allows you to customize	how the	CGI::Session object is created
	   by providing	a list of options that will be passed to the
	   CGI::Session	constructor.  Please see the documentation for
	   CGI::Session	for the	exact syntax of	the parameters.

       DEFAULT_EXPIRY
	   CGI::Session	Allows you to set an expiry time for the session.  You
	   can set the DEFAULT_EXPIRY option to	have a default expiry time set
	   for all newly created sessions.  It takes the same format as	the
	   $session->expiry method of CGI::Session takes.  Note	that it	is
	   only	set for	new session, not when a	session	is reloaded from the
	   store.

       COOKIE_PARAMS
	   This	allows you to customize	the options that are used when
	   creating the	session	cookie.	 For example you could provide an
	   expiry time for the cookie by passing -expiry => '+24h'.  The -name
	   and -value parameters for the cookie	will be	added automatically
	   unless you specifically override them by providing -name and/or
	   -value parameters.  See the CGI::Cookie docs	for the	exact syntax
	   of the parameters.

	   NOTE: You can do the	following to get both the cookie name and the
	   internal name of the	CGI::Session object to be changed:

	     $self->session_config(
	       CGI_SESSION_OPTIONS => [
		 $driver,
		 $self->query,
		 \%driver_options,
		 { name	=> 'new_cookie_name' } # change	cookie and session name
	       ]
	     );

	   Also, if '-name' parameter and 'name' of session don't match	a
	   warning will	be emitted.

       SEND_COOKIE
	   If set to a true value, the module will automatically add a cookie
	   header to the outgoing headers if a new session is created (Since
	   the session module is lazy loaded, this will	only happen if you
	   make	a call to $self->session at some point to create the session
	   object).  This option defaults to true.  If it is set to false,
	   then	no session cookies will	be sent, which may be useful if	you
	   prefer URL based sessions (it is up to you to pass the session ID
	   in this case).

       The following example shows what	options	are set	by default (ie this is
       what you	would get if you do not	call session_config).

	$self->session_config(
		 CGI_SESSION_OPTIONS =>	[ "driver:File", $self->query, {Directory=>'/tmp'} ],
		 COOKIE_PARAMS	     =>	{
					  -path	 => '/',
					},
		 SEND_COOKIE	     =>	1,
	);

       Here is a more customized example that uses the PostgreSQL driver and
       sets an expiry and domain on the	cookie.

	$self->session_config(
		 CGI_SESSION_OPTIONS =>	[ "driver:PostgreSQL;serializer:Storable", $self->query, {Handle=>$dbh}	],
		 COOKIE_PARAMS	     =>	{
					  -domain  => 'mydomain.com',
					  -expires => '+24h',
					  -path	   => '/',
					  -secure  => 1,
					},
	);

   session_cookie
       This method will	add a cookie to	the outgoing headers containing	the
       session ID that was assigned by the CGI::Session	module.

       This method is called automatically the first time $self->session is
       accessed	if SEND_COOKIE was set true, which is the default, so it will
       most likely never need to be called manually.

       NOTE that if you	do choose to call it manually that a session object
       will automatically be created if	it doesn't already exist.  This
       removes the lazy	loading	benefits of the	plugin where a session is only
       created/loaded when it is required.

       It could	be useful if you want to force the cookie header to be sent
       out even	if the session is not used on this request, or if you want to
       manage the headers yourself by turning SEND_COOKIE to false.

	 # Force the cookie header to be sent including	some
	 # custom cookie parameters
	 $self->session_cookie(-secure => 1, -expires => '+1w');

   session_loaded
       This method will	let you	know if	the session object has been loaded
       yet.  In	other words, it	lets you know if $self->session	has been
       called.

	 sub cgiapp_postrun {
	   my $self = shift;
	   $self->session->flush if $self->session_loaded;;
	 }

   session_recreate
       This method will	delete the existing session, and create	a brand	new
       one for you with	a new session ID.  It copies over all existing
       parameters into the new session.

       This can	be useful to protect against some login	attacks	when storing
       authentication tokens in	the session.  Very briefly, an attacker	loads
       a page on your site and creates a session, then tries to	trick a	victim
       into loading this page with the same session ID (possibly by embedding
       it in a URL).  Then if the victim follows the link and subsequently
       logs into their account,	the attacker will have a valid session ID
       where the session is now	logged in, and hence the attacker has access
       to the victims account.

	 sub mylogin {
	   my $self = shift;
	   if ($newly_authenticated) {
	       $self->session_recreate;
	   }
	 }

   session_delete
       This method will	perform	a more comprehensive clean-up of the session,
       calling both the	CGI::Session delete() method, but also deleting	the
       cookie from the client, if you are using	cookies.

	 sub logout {
	   my $self = shift;
	   $self->session_delete;
	   # what now?	redirect user back to the homepage?
	 }

EXAMPLE
       In a CGI::Application module:

	 # configure the session once during the init stage
	 sub cgiapp_init {
	   my $self = shift;

	   # Configure the session
	   $self->session_config(
	      CGI_SESSION_OPTIONS => [ "driver:PostgreSQL;serializer:Storable",	$self->query, {Handle=>$self->dbh} ],
	      DEFAULT_EXPIRY	  => '+1w',
	      COOKIE_PARAMS	  => {
				       -expires	=> '+24h',
				       -path	=> '/',
				     },
	      SEND_COOKIE	  => 1,
	   );

	 }

	 sub cgiapp_prerun {
	   my $self = shift;

	   # Redirect to login,	if necessary
	   unless ( $self->session->param('~logged-in')	) {
	     $self->prerun_mode('login');
	   }
	 }

	 sub my_runmode	{
	   my $self = shift;

	   # Load the template
	   my $template	= $self->load_tmpl('my_runmode.tmpl');

	   # Add all the session parameters to the template
	   $template->param($self->session->param_hashref());

	   # return the	template output
	   return $template->output;
	 }

TODO
       o   I am	considering adding support for other session modules in	the
	   future, like	Apache::Session	and possibly others if there is	a
	   demand.

       o   Possibly add	some tests to make sure	cookies	are accepted by	the
	   client.

       o   Allow a callback to be executed right after a session has been
	   created

SEE ALSO
       CGI::Application, CGI::Session, perl(1)

AUTHOR
       Cees Hek	<ceeshek@gmail.com>

LICENSE
       Copyright (C) 2004, 2005	Cees Hek <ceeshek@gmail.com>

       This library is free software. You can modify and or distribute it
       under the same terms as Perl itself.

AUTHOR
       Cees Hek	<ceeshek@gmail.com>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2013 by Cees Hek.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.32.0			  2013-12-CGI::Application::Plugin::Session(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | NAME | METHODS | EXAMPLE | TODO | SEE ALSO | AUTHOR | LICENSE | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CGI::Application::Plugin::Session&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help