---
name: "Dancer::Session::Abstract"
section: "3pm"
platform: "linux"
package: "libdancer-perl"
version: "1.3521+dfsg-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Dancer::Session::Abstract"
---

# Dancer::Session::Abstract(3pm)

abstract class for session engine

## NAME

Dancer::Session::Abstract - abstract class for session engine

## VERSION

version 1.3521

## 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\_domain*

Allows you to set the domain property on the cookie, which will override the default.  This is useful for setting the session cookie's domain to something like `".domain.com"` so that the same cookie will be applicable and usable across subdomains of a base domain.

*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.

- **get\_value($key)**

  Retrieves the value associated with the key.

- **set\_value($key, $value)**

  Stores the value associated with the key.

### 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 session ID from the cookie, ensuring it's syntactically valid.

- **write\_session\_id**

  Write the current session id to the `"dancer.session"` cookie.

- **is\_lazy**

  Default is false.  If true, session data will not be flushed after every modification and the session engine (or application) will need to ensure that a flush is called before the end of the request.

## 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.

  A *flush* is made to the session object after every modification unless the session engine overrides the `"is_lazy"` method to return true.

## AUTHOR

Dancer Core Developers

## COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Alexis Sukrieh.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.