1CGI::Application::PlugiUns:e:rSeCsosnitorni(b3u)ted PerlCGDIo:c:uAmpepnltiactaitoinon::Plugin::Session(3)
2
6 CGI::Application::Plugin::Session - Add CGI::Session support to
7 CGI::Application
8
10 use CGI::Application::Plugin::Session;
11 my $language = $self->session->param('language');
13
15 CGI::Application::Plugin::Session seamlessly adds session support to
16 your CGI::Application modules by providing a CGI::Session object that
17 is accessible from anywhere in the application.
18 Lazy loading is used to prevent expensive file system or database calls
20 from being made if the session is not needed during this request. In
21 other words, the Session object is not created until it is actually
22 needed. Also, the Session object will act as a singleton by always
23 returning the same Session object for the duration of the request.
24 This module aims to be as simple and non obtrusive as possible. By not
26 requiring any changes to the inheritance tree of your modules, it can
27 be easily added to existing applications. Think of it as a plugin
28 module that adds a couple of new methods directly into the
29 CGI::Application namespace simply by loading the module.
30
32 session
33 This method will return the current CGI::Session object. The
34 CGI::Session object is created on the first call to this method, and
35 any subsequent calls will return the same object. This effectively
36 creates a singleton session object for the duration of the request.
37 CGI::Session will look for a cookie or param containing the session ID,
38 and create a new session if none is found. If "session_config" has not
39 been called before the first call to "session", then it will choose
40 some sane defaults to create the session object.
41 # retrieve the session object
43 my $session = $self->session;
44 - or -
46 # use the session object directly
48 my $language = $self->session->param('language');
49 session_config
51 This method can be used to customize the functionality of the
52 CGI::Application::Plugin::Session module. Calling this method does not
53 mean that a new session object will be immediately created. The
54 session object will not be created until the first call to
55 $self->session. This 'lazy loading' can prevent expensive file system
56 or database calls from being made if the session is not needed during
57 this request.
58 The recommended place to call "session_config" is in the "cgiapp_init"
60 stage of CGI::Application. If this method is called after the session
61 object has already been accessed, then it will die with an error
62 message.
63 If this method is not called at all then a reasonable set of defaults
65 will be used (the exact default values are defined below).
66 The following parameters are accepted:
68 CGI_SESSION_OPTIONS
70 This allows you to customize how the CGI::Session object is created
71 by providing a list of options that will be passed to the
72 CGI::Session constructor. Please see the documentation for
73 CGI::Session for the exact syntax of the parameters.
74 DEFAULT_EXPIRY
76 CGI::Session Allows you to set an expiry time for the session. You
77 can set the DEFAULT_EXPIRY option to have a default expiry time set
78 for all newly created sessions. It takes the same format as the
79 $session->expiry method of CGI::Session takes. Note that it is
80 only set for new session, not when a session is reloaded from the
81 store.
82 COOKIE_PARAMS
84 This allows you to customize the options that are used when
85 creating the session cookie. For example you could provide an
86 expiry time for the cookie by passing -expiry => '+24h'. The -name
87 and -value parameters for the cookie will be added automatically
88 unless you specifically override them by providing -name and/or
89 -value parameters. See the CGI::Cookie docs for the exact syntax
90 of the parameters.
91 NOTE: If you change the name of the cookie by passing a -name
93 parameter, remember to notify CGI::Session of the change by calling
94 CGI::Session->name('new_cookie_name').
95 SEND_COOKIE
97 If set to a true value, the module will automatically add a cookie
98 header to the outgoing headers if a new session is created (Since
99 the session module is lazy loaded, this will only happen if you
100 make a call to $self->session at some point to create the session
101 object). This option defaults to true. If it is set to false,
102 then no session cookies will be sent, which may be useful if you
103 prefer URL based sessions (it is up to you to pass the session ID
104 in this case).
105 The following example shows what options are set by default (ie this is
107 what you would get if you do not call session_config).
108 $self->session_config(
110 CGI_SESSION_OPTIONS => [ "driver:File", $self->query, {Directory=>'/tmp'} ],
111 COOKIE_PARAMS => {
112 -path => '/',
113 },
114 SEND_COOKIE => 1,
115 );
116 Here is a more customized example that uses the PostgreSQL driver and
118 sets an expiry and domain on the cookie.
119 $self->session_config(
121 CGI_SESSION_OPTIONS => [ "driver:PostgreSQL;serializer:Storable", $self->query, {Handle=>$dbh} ],
122 COOKIE_PARAMS => {
123 -domain => 'mydomain.com',
124 -expires => '+24h',
125 -path => '/',
126 -secure => 1,
127 },
128 );
129 session_cookie
131 This method will add a cookie to the outgoing headers containing the
132 session ID that was assigned by the CGI::Session module.
133 This method is called automatically the first time $self->session is
135 accessed if SEND_COOKIE was set true, which is the default, so it will
136 most likely never need to be called manually.
137 NOTE that if you do choose to call it manually that a session object
139 will automatically be created if it doesn't already exist. This
140 removes the lazy loading benefits of the plugin where a session is only
141 created/loaded when it is required.
142 It could be useful if you want to force the cookie header to be sent
144 out even if the session is not used on this request, or if you want to
145 manage the headers yourself by turning SEND_COOKIE to false.
146 # Force the cookie header to be sent including some
148 # custom cookie parameters
149 $self->session_cookie(-secure => 1, -expires => '+1w');
150 session_loaded
152 This method will let you know if the session object has been loaded
153 yet. In other words, it lets you know if $self->session has been
154 called.
155 sub cgiapp_postrun {
157 my $self = shift;
158 $self->session->flush if $self->session_loaded;;
159 }
160 session_recreate
162 This method will delete the existing session, and create a brand new
163 one for you with a new session ID. It copies over all existing
164 parameters into the new session.
165 This can be useful to protect against some login attacks when storing
167 authentication tokens in the session. Very briefly, an attacker loads
168 a page on your site and creates a session, then tries to trick a victim
169 into loading this page with the same session ID (possibly by embedding
170 it in a URL). Then if the victim follows the link and subsequently
171 logs into their account, the attacker will have a valid session ID
172 where the session is now logged in, and hence the attacker has access
173 to the victims account.
174 sub mylogin {
176 my $self = shift;
177 if ($newly_authenticated) {
178 $self->session_recreate;
179 }
180 }
181 session_delete
183 This method will perform a more comprehensive clean-up of the session,
184 calling both the CGI::Session delete() method, but also deleting the
185 cookie from the client, if you are using cookies.
186 sub logout {
188 my $self = shift;
189 $self->session_delete;
190 # what now? redirect user back to the homepage?
191 }
192
194 In a CGI::Application module:
195 # configure the session once during the init stage
197 sub cgiapp_init {
198 my $self = shift;
199 # Configure the session
201 $self->session_config(
202 CGI_SESSION_OPTIONS => [ "driver:PostgreSQL;serializer:Storable", $self->query, {Handle=>$self->dbh} ],
203 DEFAULT_EXPIRY => '+1w',
204 COOKIE_PARAMS => {
205 -expires => '+24h',
206 -path => '/',
207 },
208 SEND_COOKIE => 1,
209 );
210 }
212 sub cgiapp_prerun {
214 my $self = shift;
215 # Redirect to login, if necessary
217 unless ( $self->session->param('~logged-in') ) {
218 $self->prerun_mode('login');
219 }
220 }
221 sub my_runmode {
223 my $self = shift;
224 # Load the template
226 my $template = $self->load_tmpl('my_runmode.tmpl');
227 # Add all the session parameters to the template
229 $template->param($self->session->param_hashref());
230 # return the template output
232 return $template->output;
233 }
234
236 · I am considering adding support for other session modules in the
237 future, like Apache::Session and possibly others if there is a
238 demand.
239 · Possibly add some tests to make sure cookies are accepted by the
241 client.
242 · Allow a callback to be executed right after a session has been
244 created
245
247 CGI::Application, CGI::Session, perl(1)
248
250 Cees Hek <ceeshek@gmail.com>
251
253 Copyright (C) 2004, 2005 Cees Hek <ceeshek@gmail.com>
254 This library is free software. You can modify and or distribute it
256 under the same terms as Perl itself.
257perl v5.12.0 2010-04-3C0GI::Application::Plugin::Session(3)