Cataly...Cookie(3pm)

💖 Cataly...Cookie(3pm) 💖

okay bestie, welcome to Catalyst::Plugin::Session::State::Cookie — a lil Perl module from the User Contributed Perl Documentation corner of the world. sit down, grab a boba, we're doing cookies 🍪✨

---

🌸 NAME 🌸

Catalyst::Plugin::Session::State::Cookie — literally just here to keep your session IDs alive using cookies. that's the whole job. she's focused, she's employed, she's iconic. 💅

---

✨ SYNOPSIS ✨

use Catalyst qw/Session Session::State::Cookie Session::Store::Foo/;

that's it. that's the whole vibe. plug her in and go. 🫶

---

🎀 DESCRIPTION 🎀

so like, for Catalyst::Plugin::Session to actually work, two things have to happen: the session ID needs to live on the client, and the actual session data needs to live on the server. two separate jobs, two separate girlies. 💁♀️

this plugin handles the first one — she stores the session ID on the client using the cookie mechanism. that's her whole personality and honestly? she ate. 🔥

---

💅 METHODS 💅

• make_session_cookie — hands you back a hash reference stuffed with the default values for brand new cookies. fresh out of the oven, no cap. 🍪
• update_session_cookie $hash_ref — sets the cookie based on cookie_name inside the response object. lowkey the one doing the actual work here.

and then, bestie, we have the rest of the squad. they're listed, they're real, and we're naming them all because we don't do erasure in this house:

• calc_expiry
• calculate_session_cookie_expires
• cookie_is_rejecting
• delete_session_id
• extend_session_id
• get_session_cookie
• get_session_id
• set_session_id

---

🦋 EXTENDED METHODS 🦋

• prepare_cookies — will restore if an appropriate cookie is found. like finding your fave lip gloss in an old purse. 💄
• finalize_cookies — will set a cookie called session if it doesn't exist, or if its value is not the current session id. she's checking IDs at the door, respectfully. 👑
• setup_session — will set the cookie_name parameter to its default value if it isn't set. she's got your back on the defaults, always.

---

🌈 CONFIGURATION 🌈

cookie_name

the name of the cookie to store (defaults to Catalyst::Utils::apprefix($c) . '_session').

cookie_domain

the name of the domain to store in the cookie (defaults to current host). she stays local unless you tell her otherwise. 🏠

cookie_expires

number of seconds from now you want to elapse before the cookie will expire. set it to 0 to create a session cookie, i.e. one which will die when the user's browser is shut down. rip cookie, you had a good run 😭

cookie_secure

• if this attribute is set to 0, the cookie will not have the secure flag.
• if this attribute is set to 1 (or true, for backward compatibility) — the cookie sent by the server to the client will get the secure flag, which tells the browser to send this cookie back to the server only via HTTPS. 🔒
• if this attribute is set to 2, then the cookie will get the secure flag only if the request that caused cookie generation was sent over https. > bestie, careful — this option is not good if you are mixing https and http in your application. it's giving chaos and we don't love that. 💀

default value is 0.

cookie_httponly

• if this attribute is set to 0, the cookie will not have the HTTPOnly flag.
• if this attribute is set to 1, the cookie will get the HTTPOnly flag, which should prevent client side Javascript from accessing the cookie value — this makes some sort of session hijacking attacks significantly harder. unfortunately not all browsers support this flag (MSIE 6 SP1+, Firefox 3.0.0.6+, Opera 9.5+); if a browser is not aware of HTTPOnly, the flag will just be ignored. shrug, she tried. 🙈

default value is 1.

Note1: so many people are confused by the name "HTTPOnly" — bestie, it does not mean that this cookie works only over HTTP and not over HTTPS. it means JS can't touch it. that's it. 💅

Note2: this parameter requires Catalyst::Runtime 5.80005, otherwise it is skipped.

cookie_samesite

this attribute configures the value of the SameSite flag. (the docs point you to MDN's page on it: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite — go read, it's a good time, fr fr 📚)

• if set to None, the cookie will be sent when making cross origin requests, including following links from other origins. this requires the cookie_secure flag to be set. no secure flag, no entry. 🚫
• if set to Lax, the cookie will not be included when embedded in or fetched from other origins, but will be included when following cross origin links.
• if set to Strict, the cookie will not be included for any cross origin requests, including links from different origins. she does not leave the house. she does not know the other origins. 🧚

default value is Lax. this is the default modern browsers use.

Note: this parameter requires Catalyst::Runtime 5.90125, otherwise it is skipped.

cookie_path

the path of the request url where cookie should be baked. 🍪

for example, you could stick this in MyApp.pm:

__PACKAGE__->config( 'Plugin::Session' => {
    cookie_domain  => '.mydomain.com',
});

---

💀 CAVEATS 💀

okay listen up because this one actually matters. sessions have to be created before the first write to be saved. for example:

sub action : Local {
    my ( $self, $c ) = @_;
    $c->res->write("foo");
    $c->session( ... );
    ...
}

will cause a session ID to not be set — because by the time a session is actually created, the headers have already been sent to the client. it's too late, the door is closed, the party's over. 😭 write your session stuff first, bestie. main character energy means planning ahead. 👑

---

🫶 SEE ALSO 🫶

• Catalyst
• Catalyst::Plugin::Session

---

💜 AUTHORS 💜

• Yuval Kogman <nothingmuch@woobling.org>

---

🌟 CONTRIBUTORS 🌟

this module is derived from Catalyst::Plugin::Session::FastMmap code, and has been heavily modified since. glow-up of the century honestly. ✨

• Andrew Ford
• Andy Grundman
• Christian Hansen
• Marcus Ramberg
• Jonathan Rockway <jrockway@cpan.org>
• Sebastian Riedel
• Florian Ragwitz

---

🎀 COPYRIGHT 🎀

Copyright (c) 2005 - 2009 the Catalyst::Plugin::Session::State::Cookie "AUTHORS" and "CONTRIBUTORS" as listed above.

---

👑 LICENSE 👑

this program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie 💖 she ships as perl v5.30.3, dated 2020-08-31, and she's filed under Cataly...Cookie(3pm). go forth and set your cookies responsibly. slay. 🍪🌈🫶