/ 
PAGI-0.001020
River stage one • 2 direct dependents • 2 total dependents
/ PAGI::Session

NAME

PAGI::Session - Standalone helper object for session data access

SYNOPSIS

use PAGI::Session;

# Construct from raw session data, scope, or request object
my $session = PAGI::Session->new($scope->{'pagi.session'});
my $session = PAGI::Session->new($scope);
my $session = PAGI::Session->new($req);  # any object with ->scope

# Strict get - dies if key doesn't exist (catches typos)
my $user_id = $session->get('user_id');

# Safe get with default for optional keys
my $theme = $session->get('theme', 'light');

# Set, delete, check existence
$session->set('cart_count', 3);
$session->delete('cart_count');
if ($session->exists('user_id')) { ... }

# List user keys (excludes internal _prefixed keys)
my @keys = $session->keys;

# Session lifecycle
$session->regenerate;  # Request new session ID
$session->destroy;     # Mark session for deletion

DESCRIPTION

PAGI::Session wraps the raw session data hashref and provides a clean accessor interface with strict key checking. It is a standalone helper that is not attached to any request or protocol object.

The strict get() method dies when a key does not exist, catching typos at runtime. Use the two-argument form get($key, $default) for keys that may or may not be present.

CONSTRUCTOR

new

my $session = PAGI::Session->new($data_hashref);
my $session = PAGI::Session->new($scope);
my $session = PAGI::Session->new($request);

Accepts raw session data (hashref), a PAGI scope (hashref with pagi.session key), or any object with a scope() method (e.g., PAGI::Request). The helper stores a reference to the underlying hash, so mutations via set() and delete() are visible to the session middleware.

METHODS

id

my $id = $session->id;

Returns the session ID from $data->{_id}.

get

my $value = $session->get('key');           # dies if missing
my $value = $session->get('key', $default); # returns $default if missing

Retrieves a value from the session. With one argument, dies with an error including the key name if the key does not exist. With a default argument, returns the default when the key is missing (even if the default is undef).

set

$session->set('key', $value);
$session->set(user_id => 42, role => 'admin', email => 'john@example.com');

Sets one or more keys in the session data. With two arguments, sets a single key. With more arguments, treats them as key-value pairs. Dies if given an odd number of arguments greater than one.

exists

if ($session->exists('key')) { ... }

Returns true if the key exists in the session data.

delete

$session->delete('key');
$session->delete('k1', 'k2', 'k3');

Removes one or more keys from the session data.

keys

my @keys = $session->keys;

Returns a list of user keys, filtering out internal keys that start with an underscore (e.g. _id, _created, _last_access).

slice

my %data = $session->slice('user_id', 'role', 'email');

Returns a hash of key-value pairs for the requested keys. Keys that do not exist in the session are silently skipped (unlike get(), which dies on missing keys).

clear

$session->clear;

Removes all user keys from the session, preserving internal _-prefixed keys (_id, _created, _last_access, etc.). Use this for a "soft logout" that keeps the session ID but wipes application data.

regenerate

$session->regenerate;

Requests session ID regeneration. The middleware will generate a new session ID, delete the old session from the store, save session data under the new ID, and update the client cookie/header.

Security: Always call this after authentication (login) to prevent session fixation attacks.

destroy

$session->destroy;

Marks the session for destruction. The middleware will delete the session data from the store and clear the client-side state (e.g., expire the cookie). Use this for logout.

SEE ALSO

PAGI::Middleware::Session - Session management middleware