NAME¶
Dancer::Session::Abstract - abstract class for session engine
SPEC¶
- role
- A Dancer::Session object represents a session engine and
should provide anything needed to manipulate a session, whatever its
storing engine is.
- id
- The session id will be written to a cookie, by default
named "dancer.session", it is assumed that a client must accept
cookies to be able to use a session-aware Dancer webapp. (The cookie name
can be change using the "session_name" config setting.)
- storage engine
- When the session engine is enabled, a before filter
takes care to initialize the appropriate session engine (according to the
setting "session").
Then, the filter looks for a cookie named "dancer.session" (or
whatever you've set the "session_name" setting to, if you've
used it) in order to retrieve the current session object. If not
found, a new session object is created and its id written to the
cookie.
Whenever a session call is made within a route handler, the singleton
representing the current session object is modified.
After terminating the request, a flush is made to the session
object.
DESCRIPTION¶
This virtual class describes how to build a session engine for Dancer. This is
done in order to allow multiple session storage backends with a common
interface.
Any session engine must inherit from Dancer::Session::Abstract and implement the
following abstract methods.
Configuration¶
These settings control how a session acts.
session_name
The default session name is "dancer_session". This can be set in your
config file:
setting session_name: "mydancer_session"
session_secure
The user's session id is stored in a cookie. If true, this cookie will be made
"secure" meaning it will only be served over https.
session_expires
When the session should expire. The format is either the number of seconds in
the future, or the human readable offset from "expires" in
Dancer::Cookie.
By default, there is no expiration.
session_is_http_only
This setting defaults to 1 and instructs the session cookie to be created with
the "HttpOnly" option active, meaning that JavaScript will not be
able to access to its value.
Abstract Methods¶
- retrieve($id)
- Look for a session with the given id, return the session
object if found, undef if not.
- create()
- Create a new session, return the session object.
- flush()
- Write the session object to the storage engine.
- destroy()
- Remove the current session object from the storage
engine.
- session_name (optional)
- Returns a string with the name of cookie used for storing
the session ID.
You should probably not override this; the user can control the cookie name
using the "session_name" setting.
Inherited Methods¶
The following methods are not supposed to be overloaded, they are generic and
should be OK for each session engine.
- build_id
- Build a new uniq id.
- read_session_id
- Reads the "dancer.session" cookie.
- write_session_id
- Write the current session id to the
"dancer.session" cookie.