Session
Session Management
Session handler documentation can be found here.
By default, sessions are stored in the database but can be configured to use the cache system. This allows session data to be debuggable in non-production environments, while in production, storing sessions in cache enhances performance.
Caution
Issues with storing sessions in transactional database
Storing a session in the database can be problematic when using transactions, as the database connection is tied to that session. Rolling back or failing a transaction may result in failed updates to the session data. It’s important to carefully consider this when designing your application’s session management strategy.
Session Functions
The session management system includes the following functions:
- authorizeUser: Authorizes a user and initiates their session.
- revokeUser: Revokes a user’s session and logs them out.
- getRole: Retrieves the role of the current user.
- isRole: Checks if the current user has a specific role.
Supplying Your Own Session
Sukarix\Core\SessionInterface declares what the framework itself requires of a session.
An application that needs a different implementation — a stateless JWT session for an API,
for instance — implements the interface and registers it under the session alias in
config/classes.ini:
[classes]
session = App\Core\Session
The contract is deliberately small. It covers only the methods Sukarix calls on
$this->session, so an implementation is free to omit the database-backed extras such as
isRole() or generateToken():
| Method | Purpose |
|---|---|
cleanupOldSessions() | Discard sessions that are no longer current |
set($key, $value) | Store a runtime value |
get($key) | Read a runtime value |
isLoggedIn() | Whether a user is authenticated |
getRole() | Role name of the authenticated user, or the guest role |
validateToken() | Whether the request carries a valid anti-forgery token |
A session that does not use anti-forgery tokens — because the caller authenticates with a
bearer token that a browser will not send on its own — returns true from
validateToken().
Note
Sukarix Convention: the contract is the framework’s requirement
SessionInterfaceis not the full surface ofSukarix\Core\Session; it is what the framework needs in order to run. The library’s own test suite asserts that every method Sukarix calls on a session is declared in the interface, so the two cannot drift apart.
Session-Free Routes
Routes under SECURITY.stateless.prefixes are served without opening a session. The
default is /api, on the assumption that an API authenticates each request by its own
means.
; Serve /api and /hooks without a session.
SECURITY.stateless.prefixes = /api,/hooks
An application whose API does rely on the session — one authenticating with a JWT session, for example — turns the behaviour off by declaring the setting empty:
; Every route opens a session.
SECURITY.stateless.prefixes =
Caution
Declaring the setting empty is not the same as omitting it
Leaving the key out entirely keeps the
/apidefault. Writing it with nothing after the equals sign is how an application says that no route is session free.