sessions

introduction

since http driven applications are stateless, sessions provide a way to store information about the user across multiple requests. dframework provides an elegant Session facade available globally to interact with session data, regardless of the underlying storage driver.

configuration

your application's session driver configuration is determined by the app.sessionDriver property. by default, the framework may use memory, database, or stealth drivers to persist session state.

interacting with the session

retrieving data

to retrieve an item from the session, use the get method on the global Session facade. you may pass a default value as the second argument, which will be returned if the specified key does not exist.

1// retrieve a specific key
2const value = await Session.get('key');
3 
4// retrieve a key with a default fallback
5const name = await Session.get('name', 'guest');

storing data

to store data in the session, use the set method.

1await Session.set('key', 'value');

if you need to store data permanently (using a ten year long lived cookie), use the permanent method.

1await Session.permanent({ role: 'admin', accepted_terms: true });

flash data

sometimes you may wish to store items in the session for the next request only. you may do so using the flash method. data stored using this method will be available immediately and during the subsequent http request, after which it will be automatically deleted. this is highly useful for short lived status messages.

1await Session.flash('status', 'profile updated successfully');

deleting data

to remove a piece of data from the session, use the forget method and pass the specific key. if you call forget without any arguments, the entire session will be destroyed and the cookie will be invalidated.

1// forget a single key
2await Session.forget('key');
3 
4// destroy the entire session
5await Session.forget();

session drivers

dframework abstracts away the complexity of session storage behind simple drivers.

• memory: stores sessions in ram. fast, but lost on server restart. suitable for local development.
• database: stores sessions in a dedicated database table. highly robust and scalable across multiple server instances.

stealth mode

dframework includes a highly unique stealth session driver. when stealth mode is enabled, session data is completely stateless on the server side. instead, the entire session payload is encrypted using aes-256-gcm and stored directly inside the user's secure http only session cookie.

this entirely eliminates the need for database lookups or memory overhead during session validation, allowing for extreme performance scaling while guaranteeing absolute data integrity and tamper detection.