1Dancer2::Core::Role::SeUssseironCFoancttroirbyu(t3e)d PeDralncDeorc2u:m:eCnotraet:i:oRnole::SessionFactory(3)
2
3
4

NAME

6       Dancer2::Core::Role::SessionFactory - Role for session factories
7

VERSION

9       version 0.300004
10

DESCRIPTION

12       Any class that consumes this role will be able to store, create,
13       retrieve and destroy session objects.
14
15       The default values for attributes can be overridden in your Dancer2
16       configuration. See "Session-engine" in Dancer2::Config.
17

ATTRIBUTES

19   cookie_name
20       The name of the cookie to create for storing the session key
21
22       Defaults to "dancer.session"
23
24   cookie_domain
25       The domain of the cookie to create for storing the session key.
26       Defaults to the empty string and is unused as a result.
27
28   cookie_path
29       The path of the cookie to create for storing the session key.  Defaults
30       to "/".
31
32   cookie_duration
33       Default duration before session cookie expiration.  If set, the
34       Dancer2::Core::Session "expires" attribute will be set to the current
35       time plus this duration (expression parsed by Dancer2::Core::Time).
36
37   session_duration
38       Duration in seconds before sessions should expire, regardless of cookie
39       expiration.  If set, then SessionFactories should use this to enforce a
40       limit on session validity.
41
42   is_secure
43       Boolean flag to tell if the session cookie is secure or not.
44
45       Default is false.
46
47   is_http_only
48       Boolean flag to tell if the session cookie is http only.
49
50       Default is true.
51

INTERFACE

53       Following is the interface provided by this role. When specified the
54       required methods to implement are described.
55
56   create
57       Create a brand new session object and store it. Returns the newly
58       created session object.
59
60       Triggers an exception if the session is unable to be created.
61
62           my $session = MySessionFactory->create();
63
64       This method does not need to be implemented in the class.
65
66   generate_id
67       Returns a randomly-generated, guaranteed-unique string.  By default, it
68       is a 32-character, URL-safe, Base64 encoded combination of a 32 bit
69       timestamp and a 160 bit SHA1 digest of random seed data.  The timestamp
70       ensures that session IDs are generally monotonic.
71
72       The default algorithm is not guaranteed cryptographically secure, but
73       it's still reasonably strong for general use.
74
75       If you have installed Math::Random::ISAAC::XS and Crypt::URandom, the
76       seed data will be generated from a cryptographically-strong random
77       number generator.
78
79       This method is used internally by create() to set the session ID.
80
81       This method does not need to be implemented in the class unless an
82       alternative method for session ID generation is desired.
83
84   validate_id
85       Returns true if a session id is of the correct format, or false
86       otherwise.
87
88       By default, this ensures that the session ID is a string of characters
89       from the Base64 schema for "URL Applications" plus the "~" character.
90
91       This method does not need to be implemented in the class unless an
92       alternative set of characters for session IDs is desired.
93
94   retrieve
95       Return the session object corresponding to the session ID given. If
96       none is found, triggers an exception.
97
98           my $session = MySessionFactory->retrieve(id => $id);
99
100       The method "_retrieve" must be implemented.  It must take $id as a
101       single argument and must return a hash reference of session data.
102
103   change_id
104       Changes the session ID of the corresponding session.
105
106           MySessionFactory->change_id(session => $session_object);
107
108       The method "_change_id" must be implemented. It must take $old_id and
109       $new_id as arguments and change the ID from the old one to the new one
110       in the underlying session storage.
111
112   destroy
113       Purges the session object that matches the ID given. Returns the ID of
114       the destroyed session if succeeded, triggers an exception otherwise.
115
116           MySessionFactory->destroy(id => $id);
117
118       The "_destroy" method must be implemented. It must take $id as a single
119       argument and destroy the underlying data.
120
121   flush
122       Make sure the session object is stored in the factory's backend. This
123       method is called to notify the backend about the change in the session
124       object.
125
126       The Dancer application will not call flush unless the session
127       "is_dirty" attribute is true to avoid unnecessary writes to the
128       database when no data has been modified.
129
130       An exception is triggered if the session is unable to be updated in the
131       backend.
132
133           MySessionFactory->flush(session => $session);
134
135       The "_flush" method must be implemented.  It must take two arguments:
136       the $id and a hash reference of session data.
137
138   set_cookie_header
139       Sets the session cookie into the response object
140
141           MySessionFactory->set_cookie_header(
142               response  => $response,
143               session   => $session,
144               destroyed => undef,
145           );
146
147       The "response" parameter contains a Dancer2::Core::Response object.
148       The "session" parameter contains a Dancer2::Core::Session object.
149
150       The "destroyed" parameter is optional.  If true, it indicates the
151       session was marked destroyed by the request context.  The default
152       "set_cookie_header" method doesn't need that information, but it is
153       included in case a SessionFactory must handle destroyed sessions
154       differently (such as signalling to middleware).
155
156   cookie
157       Coerce a session object into a Dancer2::Core::Cookie object.
158
159           MySessionFactory->cookie(session => $session);
160
161   sessions
162       Return a list of all session IDs stored in the backend.  Useful to
163       create cleaning scripts, in conjunction with session's creation time.
164
165       The "_sessions" method must be implemented.  It must return an array
166       reference of session IDs (or an empty array reference).
167

CONFIGURATION

169       If there are configuration values specific to your session factory in
170       your config.yml or environment, those will be passed to the constructor
171       of the session factory automatically.  In order to accept and store
172       them, you need to define accessors for them.
173
174           engines:
175             session:
176               Example:
177                 database_connection: "some_data"
178
179       In your session factory:
180
181           package Dancer2::Session::Example;
182           use Moo;
183           with "Dancer2::Core::Role::SessionFactory";
184
185           has database_connection => ( is => "ro" );
186
187       You need to do this for every configuration key. The ones that do not
188       have accessors defined will just go to the void.
189

AUTHOR

191       Dancer Core Developers
192

194       This software is copyright (c) 2020 by Alexis Sukrieh.
195
196       This is free software; you can redistribute it and/or modify it under
197       the same terms as the Perl 5 programming language system itself.
198
199
200
201perl v5.32.0                      2020-07D-a2n8cer2::Core::Role::SessionFactory(3)
Impressum