Cataly...:Store(3pm)

✨ NAME ✨

Catalyst::Plugin::Session::Store — the base class for session storage drivers 💖

(quick heads up: this page ships as Cataly...:Store(3pm), a Perl manual page from User Contributed Perl Documentation, iykyk 🫶)

🌸 SYNOPSIS 🌸

package Catalyst::Plugin::Session::Store::MyBackend;
use base qw/Catalyst::Plugin::Session::Store/;

💅 DESCRIPTION 💅

okay so real talk bestie: this class does literally nothing on its own. no cap. its whole personality is being a base class. But!! when the Catalyst::Plugin::Session module sets up, it will check to see that YourApp->isa("Catalyst::Plugin::Session::Store"). So when you write a session storage plugin, you should subclass this module — for exactly that reason. ✨

Also, and this is lowkey important: this documentation is intended for authors of session storage plugins, not for end users. if you're just out here using sessions in your app, this isn't your page. 🙈

🧚 WRITING STORE PLUGINS 🧚

All session storage plugins need to adhere to the following interface specification to work correctly, periodt:

⭐ Required Methods ⭐

• get_session_data $key
• store_session_data $key, $data — retrieve or store session data by key 💾

So like, $data is currently either a hash reference (for most keys) or an integer value (for expires), but all value types should be supported. yes queen, all of them.

Keys are in the format prefix:id, where prefix is session, expires, or flash, and id is always the session ID. Plugins such as Catalyst::Plugin::Session::PerUser store extensions to this format, such as user:username.

It is suggested that the store should split on the colon and store the data more efficiently — the API should remain stable, with the possible addition of new prefixes in the future.

For example, Store::DBI maps expires:id a column of session:id by special-casing get_session_data and store_session_data for that key format, in order to ease the implementation of delete_expired_sessions.

The only assurance stores are required to make is that given

$c->store_session_data( $x, $y );

for any $x,

$y == $c->get_session_data( $x )

will hold.

• store_session_data ( $key, $data ) — store a session whose KEY is the first parameter and data is the second parameter in storage.

The second parameter is a hash reference, which should normally be serialized (and later deserialized by get_session_data).

• delete_session_data ( $key ) — delete the session whose KEY is the parameter. bye bye session 🦋
• delete_expired_sessions — this method is not called by any code at present, but may be called in the future, as part of a Catalyst-specific maintenance script.

If you are wrapping around a backend which manages its own auto expiry you can just give this method an empty body. slay, zero effort 💅

😭 Error handling 😭

All errors should be thrown using Catalyst::Exception. Return values are not checked, and are assumed to be OK. Missing values are not errors.

🔥 Auto-Expiry on the Backend 🔥

Storage plugins are encouraged to use $c->session_expires, $c->config('Plugin::Session' => { expires => $val }), or the storage of the expires:$sessionid key to perform more efficient expiration — but only for the key prefixes session, flash and expires.

If the backend chooses not to do so, Catalyst::Plugin::Session will detect expired sessions as they are retrieved and delete them if necessary.

⚠️ note that session store that use this approach may leak disk space, since nothing will actively delete an expired session. The delete_expired_sessions method is there so that regularly scheduled maintenance scripts can give your backend the opportunity to clean up. not the vibe you want fr fr 😭

👑 Early Finalization 👑

By default the main session plugin will finalize during body finalization, which ensures that all controller code related to the session has completed. But some storage plugins may wish to finalize earlier — during header finalization. For example a storage that saved state in a client cookie would wish this. 👑

If a storage plugin wants to finalize early it should set $c->_needs_early_session_finalization to true. Please note that if you do this in a storage plugin, you should warn users not to attempt to change or add session keys if you use a streaming or socket interface such as $c->res->write, $c->res->write_fh or $c->req->io_fh. rainbow-flag warning, bestie 🌈

---

aaaand that's the whole page!! 💖 this one came to you from perl v5.40.1, dated 2025-08-10, filed under Cataly...:Store(3pm), and lovingly served from User Contributed Perl Documentation. go write an iconic store plugin, you got this 🎀✨