/ 
Concierge-v0.5.6
/ Concierge::User

NAME

Concierge::User - User object enabled by Concierge

VERSION

v0.5.6

SYNOPSIS

# User objects are created by Concierge lifecycle methods,
# not directly by applications.

my $login = $concierge->login_user({
    user_id  => 'alice',
    password => 'secret123',
});
my $user = $login->{user};

# Identity
say $user->user_id;       # "alice"
say $user->user_key;      # random token
say $user->session_id;    # random hex string

# Status
say $user->is_logged_in;  # 1
say $user->is_guest;      # 0
say $user->is_visitor;    # 0

# User data (from memory snapshot)
say $user->moniker;
say $user->email;
say $user->get_user_field('role');

# Update user data (writes to backend and memory)
$user->update_user_data({ theme => 'dark' });

# Refresh from backend
$user->refresh_user_data;

# Session data (get, merge-update, save in one call)
my $data = $user->get_session_data;
$user->update_session_data({ last_page => '/dashboard' });

# Raw session access when needed
my $session = $user->session;

DESCRIPTION

Concierge::User represents a user operating an instance of the application. Objects are created by Concierge's lifecycle methods (admit_visitor, checkin_guest, login_user) and returned to the application.

The available methods depend on the user's participation level:

Visitor -- identity and status methods only
Guest -- adds session access
Logged-in -- adds user data access, backend read/write

Logged-in user objects hold a snapshot of user data in memory. The refresh_user_data and update_user_data methods synchronize with the backend storage via closures provided at construction time. The user object does not need to know about or contact the concierge to access its backends.

CONSTRUCTOR

enable_user

my $user = Concierge::User->enable_user($user_id, \%options);

Called internally by Concierge. Applications should not call this directly.

%options may include:

session -- a Concierge::Sessions::Session object
user_data -- hashref of user data fields
user_key -- reuse an existing key (otherwise one is generated)
_get_user_data -- closure for reading from the Users backend
_update_user_data -- closure for writing to the Users backend

METHODS

Identity

user_id

my $id = $user->user_id;

Returns the user's identifier string.

user_key

my $key = $user->user_key;

Returns the user's key token. For visitors and guests, this is the same as the generated user_id. For logged-in users, it is a separate random token.

session_id

my $sid = $user->session_id;

Returns the session ID, or undef if the user has no session (visitors).

Status

is_visitor

Returns 1 if the user is a visitor (no session, no user data).

is_guest

Returns 1 if the user is a guest (has session, no user data).

is_logged_in

Returns 1 if the user is logged in (has session and user data).

Session Access

session

my $session = $user->session;

Returns the Concierge::Sessions::Session object, or undef for visitors. The session object provides get_data, set_data, save, and status methods.

get_session_data

my $data = $user->get_session_data;

Returns the user's session data as a hashref, or an empty hashref if no data has been stored. Returns undef for visitors (no session).

update_session_data

$user->update_session_data({ cart => \@items, last_page => '/shop' });

Merges %updates into the existing session data and saves to persistent storage. Existing keys not present in %updates are preserved. Returns 1 on success, undef if the user has no session (visitors).

User Data -- Memory Snapshot

These methods read from the in-memory data snapshot loaded at login time. They return undef for visitors and guests.

moniker

email

user_status

access_level

get_user_field

my $value = $user->get_user_field('role');

Returns the value of any field in the user data snapshot.

User Data -- Backend Operations

These methods require a logged-in user (backend closures must be present). They return undef if called on a visitor or guest.

refresh_user_data

$user->refresh_user_data;

Fetches fresh data from the Users backend and replaces the in-memory snapshot. Returns 1 on success, undef on failure.

update_user_data

$user->update_user_data({ theme => 'dark', role => 'editor' });

Writes %updates to the Users backend and merges them into the in-memory snapshot. Returns 1 on success, undef on failure.

SEE ALSO

Concierge -- creates User objects via lifecycle methods

Concierge::Sessions::Session -- session object API

AUTHOR

Bruce Van Allen <bva@cruzio.com>

LICENSE

This module is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.