File Coverage

blib/lib/Dancer2/Core/Session.pm
Criterion Covered Total %
statement 17 17 100.0
branch n/a
condition n/a
subroutine 6 6 100.0
pod 3 3 100.0
total 26 26 100.0


line stmt bran cond sub pod time code
1             package Dancer2::Core::Session;
2             # ABSTRACT: class to represent any session object
3             $Dancer2::Core::Session::VERSION = '1.0.0';
4 116     116   70373 use Moo;
  116         6773  
  116         871  
5 116     116   42202 use Dancer2::Core::Types;
  116         359  
  116         902  
6 116     116   1506514 use Dancer2::Core::Time;
  116         400  
  116         47230  
7              
8             has id => (
9             # for some specific plugins this should be rw.
10             # refer to https://github.com/PerlDancer/Dancer2/issues/460
11             is => 'rw',
12             isa => Str,
13             required => 1,
14             );
15              
16             has data => (
17             is => 'ro',
18             lazy => 1,
19             default => sub { {} },
20             );
21              
22             has expires => (
23             is => 'rw',
24             isa => Str,
25             coerce => sub {
26             my $value = shift;
27             $value += time if $value =~ /^[\-\+]?\d+$/;
28             Dancer2::Core::Time->new( expression => $value )->epoch;
29             },
30             );
31              
32             has is_dirty => (
33             is => 'rw',
34             isa => Bool,
35             default => sub {0},
36             );
37              
38              
39             sub read {
40 49     49 1 1393 my ( $self, $key ) = @_;
41 49         864 return $self->data->{$key};
42             }
43              
44              
45             sub write {
46 55     55 1 1595 my ( $self, $key, $value ) = @_;
47 55         1074 $self->is_dirty(1);
48 55         2483 $self->data->{$key} = $value;
49             }
50              
51             sub delete {
52 9     9 1 26 my ( $self, $key, $value ) = @_;
53 9         195 $self->is_dirty(1);
54 9         362 delete $self->data->{$key};
55             }
56              
57             1;
58              
59             __END__
60              
61             =pod
62              
63             =encoding UTF-8
64              
65             =head1 NAME
66              
67             Dancer2::Core::Session - class to represent any session object
68              
69             =head1 VERSION
70              
71             version 1.0.0
72              
73             =head1 DESCRIPTION
74              
75             A session object encapsulates anything related to a specific session: its ID,
76             its data, and its expiration.
77              
78             It is completely agnostic of how it will be stored, this is the role of
79             a factory that consumes L<Dancer2::Core::Role::SessionFactory> to know about that.
80              
81             Generally, session objects should not be created directly. The correct way to
82             get a new session object is to call the C<create()> method on a session engine
83             that implements the SessionFactory role. This is done automatically by the
84             app object if a session engine is defined.
85              
86             =head1 ATTRIBUTES
87              
88             =head2 id
89              
90             The identifier of the session object. Required. By default,
91             L<Dancer2::Core::Role::SessionFactory> sets this to a randomly-generated,
92             guaranteed-unique string.
93              
94             This attribute can be modified if your Session implementation requires this.
95              
96             =head2 data
97              
98             Contains the data of the session (Hash).
99              
100             =head2 expires
101              
102             Number of seconds for the expiry of the session cookie. Don't add the current
103             timestamp to it, will be done automatically.
104              
105             Default is no expiry (session cookie will leave for the whole browser's
106             session).
107              
108             For a lifetime of one hour:
109              
110             expires => 3600
111              
112             =head2 is_dirty
113              
114             Boolean value for whether data in the session has been modified.
115              
116             =head1 METHODS
117              
118             =head2 read
119              
120             Reader on the session data
121              
122             my $value = $session->read('something');
123              
124             Returns C<undef> if the key does not exist in the session.
125              
126             =head2 write
127              
128             Writer on the session data
129              
130             $session->write('something', $value);
131              
132             Sets C<is_dirty> to true. Returns C<$value>.
133              
134             =head2 delete
135              
136             Deletes a key from session data
137              
138             $session->delete('something');
139              
140             Sets C<is_dirty> to true. Returns the value deleted from the session.
141              
142             =head1 AUTHOR
143              
144             Dancer Core Developers
145              
146             =head1 COPYRIGHT AND LICENSE
147              
148             This software is copyright (c) 2023 by Alexis Sukrieh.
149              
150             This is free software; you can redistribute it and/or modify it under
151             the same terms as the Perl 5 programming language system itself.
152              
153             =cut