1CGI::Application::PlugiUns:e:rSeCsosnitorni(b3u)ted PerlCGDIo:c:uAmpepnltiactaitoinon::Plugin::Session(3)
2
6 CGI::Application::Plugin::Session - Plugin that adds session support to
7 CGI::Application
8
10 version 1.05
11
13 use CGI::Application::Plugin::Session;
14 my $language = $self->session->param('language');
16
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 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 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
35 CGI::Application::Plugin::Session - Add CGI::Session support to
36 CGI::Application
37
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 # retrieve the session object
50 my $session = $self->session;
51 - or -
53 # use the session object directly
55 my $language = $self->session->param('language');
56 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 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 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 The following parameters are accepted:
75 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 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 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 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 $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 Also, if '-name' parameter and 'name' of session don't match a
112 warning will be emitted.
113 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 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 $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 Here is a more customized example that uses the PostgreSQL driver and
136 sets an expiry and domain on the cookie.
137 $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 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 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 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 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 # Force the cookie header to be sent including some
166 # custom cookie parameters
167 $self->session_cookie(-secure => 1, -expires => '+1w');
168 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 sub cgiapp_postrun {
175 my $self = shift;
176 $self->session->flush if $self->session_loaded;;
177 }
178 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 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 sub mylogin {
194 my $self = shift;
195 if ($newly_authenticated) {
196 $self->session_recreate;
197 }
198 }
199 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 sub logout {
206 my $self = shift;
207 $self->session_delete;
208 # what now? redirect user back to the homepage?
209 }
210
212 In a CGI::Application module:
213 # configure the session once during the init stage
215 sub cgiapp_init {
216 my $self = shift;
217 # 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 }
230 sub cgiapp_prerun {
232 my $self = shift;
233 # Redirect to login, if necessary
235 unless ( $self->session->param('~logged-in') ) {
236 $self->prerun_mode('login');
237 }
238 }
239 sub my_runmode {
241 my $self = shift;
242 # Load the template
244 my $template = $self->load_tmpl('my_runmode.tmpl');
245 # Add all the session parameters to the template
247 $template->param($self->session->param_hashref());
248 # return the template output
250 return $template->output;
251 }
252
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 • Possibly add some tests to make sure cookies are accepted by the
259 client.
260 • Allow a callback to be executed right after a session has been
262 created
263
265 CGI::Application, CGI::Session, perl(1)
266
268 Cees Hek <ceeshek@gmail.com>
269
271 Copyright (C) 2004, 2005 Cees Hek <ceeshek@gmail.com>
272 This library is free software. You can modify and or distribute it
274 under the same terms as Perl itself.
275
277 Cees Hek <ceeshek@gmail.com>
278
280 This software is copyright (c) 2013 by Cees Hek.
281 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.
284perl v5.38.0 2023-10-2C3GI::Application::Plugin::Session(3)