1CGI::Application::PlugiUns:e:rSeCsosnitorni(b3u)ted PerlCGDIo:c:uAmpepnltiactaitoinon::Plugin::Session(3)
2
3
4

NAME

6       CGI::Application::Plugin::Session - Plugin that adds session support to
7       CGI::Application
8

VERSION

10       version 1.05
11

SYNOPSIS

13        use CGI::Application::Plugin::Session;
14
15        my $language = $self->session->param('language');
16

DESCRIPTION

18       CGI::Application::Plugin::Session seamlessly adds session support to
19       your CGI::Application modules by providing a CGI::Session object that
20       is accessible from anywhere in the application.
21
22       Lazy loading is used to prevent expensive file system or database calls
23       from being made if the session is not needed during this request.  In
24       other words, the Session object is not created until it is actually
25       needed.  Also, the Session object will act as a singleton by always
26       returning the same Session object for the duration of the request.
27
28       This module aims to be as simple and non obtrusive as possible.  By not
29       requiring any changes to the inheritance tree of your modules, it can
30       be easily added to existing applications.  Think of it as a plugin
31       module that adds a couple of new methods directly into the
32       CGI::Application namespace simply by loading the module.
33

NAME

35       CGI::Application::Plugin::Session - Add CGI::Session support to
36       CGI::Application
37

METHODS

39   session
40       This method will return the current CGI::Session object.  The
41       CGI::Session object is created on the first call to this method, and
42       any subsequent calls will return the same object.  This effectively
43       creates a singleton session object for the duration of the request.
44       CGI::Session will look for a cookie or param containing the session ID,
45       and create a new session if none is found.  If "session_config" has not
46       been called before the first call to "session", then it will choose
47       some sane defaults to create the session object.
48
49         # retrieve the session object
50         my $session = $self->session;
51
52         - or -
53
54         # use the session object directly
55         my $language = $self->session->param('language');
56
57   session_config
58       This method can be used to customize the functionality of the
59       CGI::Application::Plugin::Session module.  Calling this method does not
60       mean that a new session object will be immediately created.  The
61       session object will not be created until the first call to
62       $self->session.  This 'lazy loading' can prevent expensive file system
63       or database calls from being made if the session is not needed during
64       this request.
65
66       The recommended place to call "session_config" is in the "cgiapp_init"
67       stage of CGI::Application.  If this method is called after the session
68       object has already been accessed, then it will die with an error
69       message.
70
71       If this method is not called at all then a reasonable set of defaults
72       will be used (the exact default values are defined below).
73
74       The following parameters are accepted:
75
76       CGI_SESSION_OPTIONS
77           This allows you to customize how the CGI::Session object is created
78           by providing a list of options that will be passed to the
79           CGI::Session constructor.  Please see the documentation for
80           CGI::Session for the exact syntax of the parameters.
81
82       DEFAULT_EXPIRY
83           CGI::Session Allows you to set an expiry time for the session.  You
84           can set the DEFAULT_EXPIRY option to have a default expiry time set
85           for all newly created sessions.  It takes the same format as the
86           $session->expiry method of CGI::Session takes.  Note that it is
87           only set for new session, not when a session is reloaded from the
88           store.
89
90       COOKIE_PARAMS
91           This allows you to customize the options that are used when
92           creating the session cookie.  For example you could provide an
93           expiry time for the cookie by passing -expiry => '+24h'.  The -name
94           and -value parameters for the cookie will be added automatically
95           unless you specifically override them by providing -name and/or
96           -value parameters.  See the CGI::Cookie docs for the exact syntax
97           of the parameters.
98
99           NOTE: You can do the following to get both the cookie name and the
100           internal name of the CGI::Session object to be changed:
101
102             $self->session_config(
103               CGI_SESSION_OPTIONS => [
104                 $driver,
105                 $self->query,
106                 \%driver_options,
107                 { name => 'new_cookie_name' } # change cookie and session name
108               ]
109             );
110
111           Also, if '-name' parameter and 'name' of session don't match a
112           warning will be emitted.
113
114       SEND_COOKIE
115           If set to a true value, the module will automatically add a cookie
116           header to the outgoing headers if a new session is created (Since
117           the session module is lazy loaded, this will only happen if you
118           make a call to $self->session at some point to create the session
119           object).  This option defaults to true.  If it is set to false,
120           then no session cookies will be sent, which may be useful if you
121           prefer URL based sessions (it is up to you to pass the session ID
122           in this case).
123
124       The following example shows what options are set by default (ie this is
125       what you would get if you do not call session_config).
126
127        $self->session_config(
128                 CGI_SESSION_OPTIONS => [ "driver:File", $self->query, {Directory=>'/tmp'} ],
129                 COOKIE_PARAMS       => {
130                                          -path  => '/',
131                                        },
132                 SEND_COOKIE         => 1,
133        );
134
135       Here is a more customized example that uses the PostgreSQL driver and
136       sets an expiry and domain on the cookie.
137
138        $self->session_config(
139                 CGI_SESSION_OPTIONS => [ "driver:PostgreSQL;serializer:Storable", $self->query, {Handle=>$dbh} ],
140                 COOKIE_PARAMS       => {
141                                          -domain  => 'mydomain.com',
142                                          -expires => '+24h',
143                                          -path    => '/',
144                                          -secure  => 1,
145                                        },
146        );
147
148   session_cookie
149       This method will add a cookie to the outgoing headers containing the
150       session ID that was assigned by the CGI::Session module.
151
152       This method is called automatically the first time $self->session is
153       accessed if SEND_COOKIE was set true, which is the default, so it will
154       most likely never need to be called manually.
155
156       NOTE that if you do choose to call it manually that a session object
157       will automatically be created if it doesn't already exist.  This
158       removes the lazy loading benefits of the plugin where a session is only
159       created/loaded when it is required.
160
161       It could be useful if you want to force the cookie header to be sent
162       out even if the session is not used on this request, or if you want to
163       manage the headers yourself by turning SEND_COOKIE to false.
164
165         # Force the cookie header to be sent including some
166         # custom cookie parameters
167         $self->session_cookie(-secure => 1, -expires => '+1w');
168
169   session_loaded
170       This method will let you know if the session object has been loaded
171       yet.  In other words, it lets you know if $self->session has been
172       called.
173
174         sub cgiapp_postrun {
175           my $self = shift;
176           $self->session->flush if $self->session_loaded;;
177         }
178
179   session_recreate
180       This method will delete the existing session, and create a brand new
181       one for you with a new session ID.  It copies over all existing
182       parameters into the new session.
183
184       This can be useful to protect against some login attacks when storing
185       authentication tokens in the session.  Very briefly, an attacker loads
186       a page on your site and creates a session, then tries to trick a victim
187       into loading this page with the same session ID (possibly by embedding
188       it in a URL).  Then if the victim follows the link and subsequently
189       logs into their account, the attacker will have a valid session ID
190       where the session is now logged in, and hence the attacker has access
191       to the victims account.
192
193         sub mylogin {
194           my $self = shift;
195           if ($newly_authenticated) {
196               $self->session_recreate;
197           }
198         }
199
200   session_delete
201       This method will perform a more comprehensive clean-up of the session,
202       calling both the CGI::Session delete() method, but also deleting the
203       cookie from the client, if you are using cookies.
204
205         sub logout {
206           my $self = shift;
207           $self->session_delete;
208           # what now?  redirect user back to the homepage?
209         }
210

EXAMPLE

212       In a CGI::Application module:
213
214         # configure the session once during the init stage
215         sub cgiapp_init {
216           my $self = shift;
217
218           # Configure the session
219           $self->session_config(
220              CGI_SESSION_OPTIONS => [ "driver:PostgreSQL;serializer:Storable", $self->query, {Handle=>$self->dbh} ],
221              DEFAULT_EXPIRY      => '+1w',
222              COOKIE_PARAMS       => {
223                                       -expires => '+24h',
224                                       -path    => '/',
225                                     },
226              SEND_COOKIE         => 1,
227           );
228
229         }
230
231         sub cgiapp_prerun {
232           my $self = shift;
233
234           # Redirect to login, if necessary
235           unless ( $self->session->param('~logged-in') ) {
236             $self->prerun_mode('login');
237           }
238         }
239
240         sub my_runmode {
241           my $self = shift;
242
243           # Load the template
244           my $template = $self->load_tmpl('my_runmode.tmpl');
245
246           # Add all the session parameters to the template
247           $template->param($self->session->param_hashref());
248
249           # return the template output
250           return $template->output;
251         }
252

TODO

254       •   I am considering adding support for other session modules in the
255           future, like Apache::Session and possibly others if there is a
256           demand.
257
258       •   Possibly add some tests to make sure cookies are accepted by the
259           client.
260
261       •   Allow a callback to be executed right after a session has been
262           created
263

SEE ALSO

265       CGI::Application, CGI::Session, perl(1)
266

AUTHOR

268       Cees Hek <ceeshek@gmail.com>
269

LICENSE

271       Copyright (C) 2004, 2005 Cees Hek <ceeshek@gmail.com>
272
273       This library is free software. You can modify and or distribute it
274       under the same terms as Perl itself.
275

AUTHOR

277       Cees Hek <ceeshek@gmail.com>
278
280       This software is copyright (c) 2013 by Cees Hek.
281
282       This is free software; you can redistribute it and/or modify it under
283       the same terms as the Perl 5 programming language system itself.
284
285
286
287perl v5.38.0                      2023-10-2C3GI::Application::Plugin::Session(3)
Impressum