Cataly...legate(3pm)

💖 NAME 💖

Catalyst::Plugin::Session::Store::Delegate — bestie, this is the plugin that delegates your session storage to an application model object. Yes queen, the model does the work. 💅

---

✨ SYNOPSIS ✨

use Catalyst::Plugin::Session::Store::Delegate;

That's it. That's the whole vibe. 🦋

---

🌸 DESCRIPTION 🌸

Okay so real talk: this store plugin makes it super easy to hand off your session storage to a first-class object model. Like, you're not stuffing sessions into some dusty corner — you're giving them to a proper grown-up object that handles everything. Iconic behavior, no cap. 👑

---

🎀 THE MODEL 🎀

So the model is the thing you use to retrieve the delegate object for a given session ID. Slay.

Normally this is something like DBIC's resultset object. You know the type. 💁

The model must respond to the get_delegate method — or a closure — in the session config hash (and it defaults to get_session_store_delegate, in case you were wondering).

⚠️ An object must always be returned from this method, even if that means autovivifying. No returning undef, bestie, that's not the move. The object may optimize and create itself lazily in the actual store only when ->store methods are actually called, though. So it can be chill about it until it actually needs to show up. 🫶

---

🦋 THE DELEGATE 🦋

A single delegate belongs to a single session ID. Periodt. It provides storage space for arbitrary fields.

The delegate object must respond to method calls as per the session_store_delegate_key_to_accessor method's return values. Typically this means responding to $obj->$field type accessors. Standard.

If necessary, the delegate should maintain an internal reference count of the stored fields, so that it can garbage collect itself when all the fields have been deleted. Self-care, honestly. 🧹✨

The fields are arbitrary, and are governed by the various session plugins. (The original says "goverend" — we're keeping that typo energy, it's part of the lore. 🙈)

The basic keys that must be supported are:

• expires — a timestamp indicating when the session will expire. If a store so chooses, it may clean up session data after this timestamp, even without being told to delete. Like it just knows. 💀
• session — the main session data hash. Might not be used, if only flash exists.
• flash — a hash much like the main session data hash, which can be created and deleted multiple times per session, as required. Reusable queen. 🔥

The delegate must also respond to the flush method, which is used to tell the store delegate that no more set/get/delete methods will be invoked on it. That's the "we're done here" moment. 🎬

---

💅 METHODS 💅

• session_store_delegate_key_to_accessor $key, $operation — this method implements the various calling conventions. It accepts a $key and an operation name ("get", "set" or "delete"), and must return a method (could be a string or a code reference), plus an optional list of arguments that will be invoked on the delegate.

The default version splits $key on the first colon, extracting the field name and the ID. It then returns the unaltered field name, and if the operation is 'delete' it also provides the extra argument "undef". This works with accessor semantics like these:

$obj->foo;
$obj->foo("bar");
$obj->foo(undef);

To facilitate a convention like

$obj->get_foo;
$obj->set_foo("bar");
$obj->delete_foo;

or

$obj->get("foo");
$obj->set("foo", "bar");
$obj->delete("foo");

simply override this method. You may look in the source of this module to find commented out versions which should help you. We got you. 🫶

• session_store_delegate — this method returns the delegate, which may be cached in $c.
• get_session_store_delegate $id — this method should get the delegate object for a given ID. See "THE MODEL" for more details. Go read it. It's right up there. ⬆️
• session_store_model — this method should return the model that will provide the delegate object. The default implementation will simply return $c->model( $c->session_store_model_name ).
• session_store_model_name — returns $c->config->{session}{model_name} || "Sessions".
• finalize_session_delegate $delegate — invokes the flush method on the delegate. May be overridden if that behavior is inappropriate. Your call, bestie. ✨
• get_session_data $key
• store_session_data $key, $value
• delete_session_data $key

These methods translate the store API into the delegate API using session_store_delegate_key_to_accessor. They're the little translators, the middlemen, the go-betweens. 🌈

---

👑 AUTHORS 👑

Yuval Kogman, nothingmuch@woobling.org

Tomas Doran, (t0m) bobtfish@bobtfish.net (current maintainer)

Shoutout to these two. Legends, honestly. 🫡

---

💜 COPYRIGHT & LICENSE 💜

Copyright (c) 2006 the aforementioned authors. 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!! This was Cataly...legate(3pm) from the User Contributed Perl Documentation, running perl v5.36.0 and dated 2022-10-15. Now go delegate something. You got this. 💖✨🦋