NAME

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

SYNOPSIS

use PAGI::Session;

# Construct from scope or request object
my $session = PAGI::Session->new($scope);
my $session = PAGI::Session->new($req);  # any object with ->scope
my $session = PAGI::Session->new(@_);    # extra args ignored

# Test convenience — wrap raw data directly
my $session = PAGI::Session->from_data({ _id => 'test', user_id => 42 });

# 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($scope);
my $session = PAGI::Session->new($request);   # any object with ->scope
my $session = PAGI::Session->new(@_);          # extra args ignored

Scope-based constructor. Resolves to the $scope->{'pagi.session'} hashref. Accepts a scope hashref directly, or any blessed object with a scope() method. Extra positional arguments ($receive, $send) are silently ignored, so you can write PAGI::Session->new(@_) in a handler.

Dies if the scope does not contain a pagi.session key (session middleware must run first).

from_data

my $session = PAGI::Session->from_data({ _id => 'test', user_id => 42 });

Test convenience constructor. Wraps a raw hashref directly as the backing data, bypassing scope resolution. The returned object behaves identically to one created via new().

METHODS

id

my $id = $session->id;

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

data

my $href = $session->data;
$href->{key} = $value;  # direct mutation

Returns the raw backing hashref. Mutations are visible through get()/set() since they operate on the same reference.

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');
$session->set('a', 1)->set('b', 2);  # chaining

Sets one or more keys in the session data. Accepts key-value pairs. Returns $self for method chaining. With zero arguments, acts as a no-op returning $self. Dies if given an odd number of arguments.

exists

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

Returns true if the key exists in the session data.

delete

$session->delete('key');
$session->delete('k1', 'k2', 'k3');
$session->delete('a')->delete('b');  # chaining

Removes one or more keys from the session data. Returns $self for method chaining.

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

cpanm PAGI

perl -MCPAN -e shell
install PAGI