Cutelyst::Session Class Reference

Plugin providing methods for session management. More...

#include <Cutelyst/Plugins/Session/Session>

Inheritance diagram for Cutelyst::Session:

Public Member Functions
	Session (Application *parent)
	Session (Application *parent, const QVariantMap &defaultConfig)
virtual	~Session ()
void	setStorage (std::unique_ptr< SessionStore > store)
virtual bool	setup (Application *app) final
SessionStore *	storage () const
Public Member Functions inherited from Cutelyst::Plugin
	Plugin (Application *parent)

Static Public Member Functions
static void	changeExpires (Context *c, quint64 expires)
static QString	deleteReason (Context *c)
static void	deleteSession (Context *c, const QString &reason=QString())
static void	deleteValue (Context *c, const QString &key)
static void	deleteValues (Context *c, const QStringList &keys)
static quint64	expires (Context *c)
static QByteArray	id (Context *c)
static bool	isValid (Context *c)
static void	setValue (Context *c, const QString &key, const QVariant &value)
static QVariant	value (Context *c, const QString &key, const QVariant &defaultValue=QVariant())

Detailed Description

The Session plugin manages user sessions and uses a SessionStore to store the session data. Cutelyst already ships with session stores to store sessions in the filesystem and on memcached servers. You can create your own session store by creating a new subclass of SessionStore and set it to this plugin using setStorage().

By default, if no session store has been manually set, a SessionStoreFile will be used.

Usage example

#include <Cutelyst/Plugins/Session/Session>
#include <Cutelyst/Plugins/Session/sessionstorefile.h>
 
bool MyCutelystApp::init()
{
     // other initiaization stuff
     // ...
 
     auto sess = new Session(this);
     sess->setStorage(std::make_unique<SessionStoreFile>(sess));
 
     // maybe more initalization stuff
     // ...
}
 
void MyController::myMethod(Context *c)
{
     Session::setValue(QStringLiteral("myKey"), QStringLiteral("myValue"));
 
     // ...
}
 
void MyOtherController::myOtherMethod(Context *c)
{
     const QString myValue = Session::value(QStringLiteral("myKey")).toString();
 
     // ...
}

Configuration file options

There are some options you can set in your application configuration file in the Cutelyst_Session_Plugin section. You can set your own default values using the defaultConfig parameter of the overloaded constructor.

expires

Type: integer or string
Default: 2 hours

The expiration duration of the session. The value will be parsed by Utils::durationFromString() (since Cutelyst 4.0.0, before that, it took simple seconds), so you can use one of the supported human readable time spans.

verify_address

Type: bool
Default: false

If true, the plugin will check if the IP address of the requesting user matches the address stored in the session data. In case of a mismatch, the session will be deleted.

verify_user_agent

Type: bool
Default: false

If true, the plugin will check if the user agent of the requesting user matches the user agent stored in the session data. In case of a mismatch, the session will be deleted.

cookie_http_only

Type: bool
Default: true

If true, the session cookie will have the httpOnly flag set so that the cookie is not accessible to JavaScript’s Document.cookie API.

cookie_secure

Type: bool
Default: false

If true, the session cookie will have the secure flag set so that the cookie is only sent to the server with an encrypted request over the HTTPS protocol.

cookie_same_site

Type: string
Default: strict
Acceptable values: default,none,lax,strict

Defines the SameSite attribute of the session cookie. See MDN to learn more about SameSite cookies. Also have a look at QNetworkCookie::SameSite. This configuration key is available since Cutelyst 3.8.0.

Logging category

cutelyst.plugin.session
Logging with Cutelyst

Definition at line 160 of file session.h.

Constructor & Destructor Documentation

Session() [1/2]

Session::Session

(

Cutelyst::Application *

parent

)

Constructs a new Session object with the given parent.

Definition at line 36 of file session.cpp.

References Cutelyst::Plugin::Plugin().

Referenced by setStorage(), setup(), and storage().

Session() [2/2]

Session::Session	(	Cutelyst::Application *	parent,
		const QVariantMap &	defaultConfig )

Constructs a new Session object with the given parent and defaultConfig.

Use the defaultConfig to set default values for the configuration entries from the configuration file.

Since

Cutelyst 4.0.0

Definition at line 42 of file session.cpp.

References Cutelyst::Plugin::Plugin().

~Session()

Cutelyst::Session::~Session ( )

virtual

Destroys the Session object.

Definition at line 49 of file session.cpp.

Member Function Documentation

changeExpires()

void Session::changeExpires ( Context * c, quint64 expires )

static

Change the session expiration time for this session

Note that this only works to set the session longer than the config setting.

Definition at line 142 of file session.cpp.

References expires(), and id().

deleteReason()

QString Session::deleteReason ( Context * c )

static

This method contains a string with the reason a session was deleted. Possible values include:

• session expired
• address mismatch
• user agent mismatch

Definition at line 164 of file session.cpp.

References Cutelyst::Context::stash().

deleteSession()

void Session::deleteSession ( Context * c, const QString & reason = QString() )

static

This method is used to invalidate a session. It takes an optional reason parameter which will be saved in deleteReason if provided.

Note

This method will also delete your flash data.

Definition at line 155 of file session.cpp.

deleteValue()

void Session::deleteValue ( Context * c, const QString & key )

static

Removes the session key.

Definition at line 208 of file session.cpp.

References Cutelyst::Context::setStash(), and Cutelyst::Context::stash().

deleteValues()

void Session::deleteValues ( Context * c, const QStringList & keys )

static

Removes all session keys.

Definition at line 232 of file session.cpp.

References Cutelyst::Context::setStash(), and Cutelyst::Context::stash().

Referenced by Cutelyst::StatusMessage::load(), and Cutelyst::AuthenticationRealm::removePersistedUser().

expires()

quint64 Session::expires ( Context * c )

static

This method returns the time when the current session will expire, or 0 if there is no current session. If there is a session and it already expired, it will delete the session and return 0 as well.

Definition at line 122 of file session.cpp.

References expires(), and Cutelyst::Context::stash().

Referenced by changeExpires(), and expires().

id()

QByteArray Session::id ( Cutelyst::Context * c )

static

Returns the current session id or null if there is no current session

Definition at line 104 of file session.cpp.

References Cutelyst::Context::stash().

Referenced by changeExpires().

isValid()

bool Session::isValid ( Cutelyst::Context * c )

static

Returns true if the session is valid.

Definition at line 258 of file session.cpp.

setStorage()

void Session::setStorage

(

std::unique_ptr< SessionStore >

store

)

Sets the session store. If no store has been set manually, a SessionStoreFile will be created.

Definition at line 90 of file session.cpp.

References Session().

setup()

bool Session::setup ( Application * app )

finalvirtual

Sets up the plugin and loads the configuration.

Reimplemented from Cutelyst::Plugin.

Definition at line 54 of file session.cpp.

References Session(), Cutelyst::Application::afterDispatch(), Cutelyst::Engine::config(), Cutelyst::Utils::durationFromString(), Cutelyst::Application::engine(), and Cutelyst::Application::postForked().

setValue()

void Session::setValue ( Cutelyst::Context * c, const QString & key, const QVariant & value )

static

Sets the value for session key to value. If the key already exists, the previous value is overwritten.

Definition at line 184 of file session.cpp.

References Cutelyst::Context::setStash(), Cutelyst::Context::stash(), and value().

Referenced by Cutelyst::StatusMessage::error(), Cutelyst::StatusMessage::errorQuery(), Cutelyst::AuthenticationRealm::persistUser(), Cutelyst::StatusMessage::status(), and Cutelyst::StatusMessage::statusQuery().

storage()

SessionStore * Session::storage

(

)

const

Returns the session storage.

Definition at line 98 of file session.cpp.

References Session().

value()

QVariant Session::value ( Cutelyst::Context * c, const QString & key, const QVariant & defaultValue = QVariant() )

static

Returns the value for session key. If the session key doesn't exist, returns defaultValue.

Definition at line 169 of file session.cpp.

References Cutelyst::Context::stash().

Referenced by Cutelyst::StatusMessage::load(), setValue(), and Cutelyst::AuthenticationRealm::userIsRestorable().