local-lib5/man/man3/Catalyst::Plugin::Session::State::Cookie.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Catalyst::Plugin::Session::State::Cookie 3"
 127 .TH Catalyst::Plugin::Session::State::Cookie 3 "2009-10-18" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Catalyst::Plugin::Session::State::Cookie \- Maintain session IDs using cookies.
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&    use Catalyst qw/Session Session::State::Cookie Session::Store::Foo/;
 138 .Ve
 139 .SH "DESCRIPTION"
 140 .IX Header "DESCRIPTION"
 141 In order for Catalyst::Plugin::Session to work the session \s-1ID\s0 needs to be
 142 stored on the client, and the session data needs to be stored on the server.
 143 .PP
 144 This plugin stores the session \s-1ID\s0 on the client using the cookie mechanism.
 145 .SH "METHODS"
 146 .IX Header "METHODS"
 147 .IP "make_session_cookie" 4
 148 .IX Item "make_session_cookie"
 149 Returns a hash reference with the default values for new cookies.
 150 .ie n .IP "update_session_cookie $hash_ref" 4
 151 .el .IP "update_session_cookie \f(CW$hash_ref\fR" 4
 152 .IX Item "update_session_cookie $hash_ref"
 153 Sets the cookie based on \f(CW\*(C`cookie_name\*(C'\fR in the response object.
 154 .IP "calc_expiry" 4
 155 .IX Item "calc_expiry"
 156 .PD 0
 157 .IP "calculate_session_cookie_expires" 4
 158 .IX Item "calculate_session_cookie_expires"
 159 .IP "cookie_is_rejecting" 4
 160 .IX Item "cookie_is_rejecting"
 161 .IP "delete_session_id" 4
 162 .IX Item "delete_session_id"
 163 .IP "extend_session_id" 4
 164 .IX Item "extend_session_id"
 165 .IP "get_session_cookie" 4
 166 .IX Item "get_session_cookie"
 167 .IP "get_session_id" 4
 168 .IX Item "get_session_id"
 169 .IP "set_session_id" 4
 170 .IX Item "set_session_id"
 171 .PD
 172 .SH "EXTENDED METHODS"
 173 .IX Header "EXTENDED METHODS"
 174 .IP "prepare_cookies" 4
 175 .IX Item "prepare_cookies"
 176 Will restore if an appropriate cookie is found.
 177 .IP "finalize_cookies" 4
 178 .IX Item "finalize_cookies"
 179 Will set a cookie called \f(CW\*(C`session\*(C'\fR if it doesn't exist or if its value is not
 180 the current session id.
 181 .IP "setup_session" 4
 182 .IX Item "setup_session"
 183 Will set the \f(CW\*(C`cookie_name\*(C'\fR parameter to its default value if it isn't set.
 184 .SH "CONFIGURATION"
 185 .IX Header "CONFIGURATION"
 186 .IP "cookie_name" 4
 187 .IX Item "cookie_name"
 188 The name of the cookie to store (defaults to \f(CW\*(C`Catalyst::Utils::apprefix($c) . \*(Aq_session\*(Aq\*(C'\fR).
 189 .IP "cookie_domain" 4
 190 .IX Item "cookie_domain"
 191 The name of the domain to store in the cookie (defaults to current host)
 192 .IP "cookie_expires" 4
 193 .IX Item "cookie_expires"
 194 Number of seconds from now you want to elapse before cookie will expire.
 195 Set to 0 to create a session cookie, ie one which will die when the
 196 user's browser is shut down.
 197 .IP "cookie_secure" 4
 198 .IX Item "cookie_secure"
 199 If this attribute \fBset to 0\fR the cookie will not have the secure flag.
 200 .Sp
 201 If this attribute \fBset to 1\fR (or true for backward compatibility) \- the cookie
 202 send by the server to the client will got the secure flag that tells the browser
 203 to send this cookies back to the server only via \s-1HTTPS\s0.
 204 .Sp
 205 If this attribute \fBset to 2\fR then the cookie will got the secure flag only if
 206 the request that caused cookie generation was sent over https (this option is
 207 not good if you are mixing https and http in you application).
 208 .Sp
 209 Default vaule is 0.
 210 .IP "cookie_httponly" 4
 211 .IX Item "cookie_httponly"
 212 If this attribute \fBset to 0\fR, the cookie will not have HTTPOnly flag.
 213 .Sp
 214 If this attribute \fBset to 1\fR, the cookie will got HTTPOnly flag that should
 215 prevent client side Javascript accessing the cookie value \- this makes some
 216 sort of session hijacking attacks significantly harder. Unfortunately not all
 217 browsers support this flag (\s-1MSIE\s0 6 \s-1SP1+\s0, Firefox 3.0.0.6+, Opera 9.5+); if
 218 a browser is not aware of HTTPOnly the flag will be ignored.
 219 .Sp
 220 Default value is 1.
 221 .Sp
 222 Note1: Many peole are confused by the name \*(L"HTTPOnly\*(R" \- it \fBdoes not mean\fR
 223 that this cookie works only over \s-1HTTP\s0 and not over \s-1HTTPS\s0.
 224 .Sp
 225 Note2: This paramater requires Catalyst::Runtime 5.80005 otherwise is skipped.
 226 .IP "cookie_path" 4
 227 .IX Item "cookie_path"
 228 The path of the request url where cookie should be baked.
 229 .PP
 230 For example, you could stick this in MyApp.pm:
 231 .PP
 232 .Vb 3
 233 \&  _\|_PACKAGE_\|_\->config( \*(AqPlugin::Session\*(Aq => {
 234 \&     cookie_domain  => \*(Aq.mydomain.com\*(Aq,
 235 \&  });
 236 .Ve
 237 .SH "CAVEATS"
 238 .IX Header "CAVEATS"
 239 Sessions have to be created before the first write to be saved. For example:
 240 .PP
 241 .Vb 6
 242 \&        sub action : Local {
 243 \&                my ( $self, $c ) = @_;
 244 \&                $c\->res\->write("foo");
 245 \&                $c\->session( ... );
 246 \&                ...
 247 \&        }
 248 .Ve
 249 .PP
 250 Will cause a session \s-1ID\s0 to not be set, because by the time a session is
 251 actually created the headers have already been sent to the client.
 252 .SH "SEE ALSO"
 253 .IX Header "SEE ALSO"
 254 Catalyst, Catalyst::Plugin::Session.
 255 .SH "AUTHORS"
 256 .IX Header "AUTHORS"
 257 Yuval Kogman <nothingmuch@woobling.org>
 258 .SH "CONTRIBUTORS"
 259 .IX Header "CONTRIBUTORS"
 260 This module is derived from Catalyst::Plugin::Session::FastMmap code, and
 261 has been heavily modified since.
 262 .PP
 263 .Vb 7
 264 \&  Andrew Ford
 265 \&  Andy Grundman
 266 \&  Christian Hansen
 267 \&  Marcus Ramberg
 268 \&  Jonathan Rockway E<lt>jrockway@cpan.orgE<gt>
 269 \&  Sebastian Riedel
 270 \&  Florian Ragwitz
 271 .Ve
 272 .SH "COPYRIGHT"
 273 .IX Header "COPYRIGHT"
 274 Copyright (c) 2005 \- 2009
 275 the Catalyst::Plugin::Session::State::Cookie \*(L"\s-1AUTHORS\s0\*(R" and \*(L"\s-1CONTRIBUTORS\s0\*(R"
 276 as listed above.
 277 .SH "LICENSE"
 278 .IX Header "LICENSE"
 279 This program is free software, you can redistribute it and/or modify it
 280 under the same terms as Perl itself.