PHP Luminova: Backend Sessions and Client Login Session Management

The Luminova backend Session manager is a useful component designed to simplify managing user data and logins of your in PHP session or cookie storage for Luminova web applications. It provides methods to enhance the storage and retrieval of session data, enabling applications to maintain stateful interactions with users across multiple requests. The session manager supports two distinct storage managers:

• Luminova\Sessions\Managers\Session
• Luminova\Sessions\Managers\Cookie

Additionally, it offers two session handler implementations:

• Luminova\Sessions\Handlers\Database
• Luminova\Sessions\Handlers\Filesystem

This flexibility allows developers to choose the most suitable storage mechanism and handler based on their application's requirements.

Storage Managers

The storage managers in Luminova Luminova\Sessions\Managers\Session and Luminova\Sessions\Managers\Cookie, handle the storing and retrieval of session data. They provide features to define a base storage table name through the session configuration class (App\Config\Session->tableIndex), where all application session data is stored. These managers also allow customization of the session storage name, which controls where the session instance stores, retrieves, and manages data in application session table tableIndex.

Session Storage Manager

The Luminova\Sessions\Managers\Session manager uses PHP's default $_SESSION superglobal to store and retrieve session data, ensuring seamless integration with standard PHP session handling.

Cookie Storage Manager

The Luminova\Sessions\Managers\Cookie manager uses PHP's setcookie and $_COOKIE mechanisms to manage session data, offering an alternative for applications that prefer cookie-based storage.

Session Handlers

Luminova provides two session handler implementations Luminova\Sessions\Handlers\Database and Luminova\Sessions\Handlers\Filesystem. These handlers override PHP's default session handling, enabling the storage of session data in a database or filesystem. They also support ip address binding, data encryption and decryption, allowing secure transfer and management of session data. Encrypted session data can only be decrypted by applications using the same encryption key.

Database Handler

The Luminova\Sessions\Handlers\Database allows session data to be stored in a database, providing scalability and centralized session management.

Filesystem Handler

The Luminova\Sessions\Handlers\Filesystem stores session data in the filesystem, offering simplicity and ease of use for smaller-scale applications.

Array Handler

The Luminova\Sessions\Handlers\ArrayHandler provides an in-memory session storage mechanism using a static array. This approach offers fast read/write operations and is ideal for lightweight applications, unit testing, or scenarios where persistence is unnecessary.

Unlike file-based or database-backed session handlers, ArrayHandler does not retain session data across requests, making it suitable for ephemeral session storage needs. It supports encryption, custom validation, and lifecycle event callbacks for flexible session handling.

Custom Session Handlers

In addition to the built-in handlers, Luminova provides a Luminova\Base\BaseSessionHandler class. Developers can extend this abstract base class to implement custom session handlers to meet their specific application needs.

Note: The Luminova\Sessions\Session class is designed for backend session management, prioritizing enhanced security and scalability.

Examples

Initializes the session storage driver of your choice.

use Luminova\Sessions\Session;
use Luminova\Sessions\Managers\Session as SessionManager;

$session = new Session(new SessionManager());
$session->start();

With Cookie Manager

Cookie manager, this manager will store your user information in cookie storage which is client-side storage.

use Luminova\Sessions\Session;
use Luminova\Sessions\Managers\Cookie as CookieManager;

$session = new Session(new CookieManager());
$session->start();

With Database Handler

This will overwrite the default PHP session storage with a database handler. For more information about the database handler, refer to the Database Session Handler Documentation.

use Luminova\Sessions\Session;
use Luminova\Sessions\Handlers\Database;

$session = new Session();
$session->setHandler(new Database('tableName'));
$session->start();

Note: By default access to JavaScript is not allowed on and cookie should only be transmitted over secure HTTPS connection.

Class Definition

• Class namespace: \Luminova\Sessions\Session
• This class implements: \Luminova\Interface\LazyInterface

Methods

constructor

Initializes session class with your preferred manager class, such as Luminova\Sessions\Managers\Session or Luminova\Sessions\Managers\Cookie.

This constructor sets up the session manager to handle user login and backend session management.It allows for an optional custom session manager and session handler to be provided or defaults to the standard manager.

If not provided, the default \Luminova\Sessions\Managers\Session will be used as default.

public __construct(?\Luminova\Interface\SessionManagerInterface $manager = null): mixed

Parameters:

Note: When no custom manager is provided, the default session manager is automatically initialized and configured using the session configuration settings.

getInstance

Singleton method to return an instance of the Session class.

public static getInstance(?\Luminova\Interface\SessionManagerInterface $manager = null): static

Parameters:

Return Value:

static - Return a shared instance of session class.

getManager

Retrieves the current session storage manager instance.

This method returns the session manager instance responsible for handlingsession data, either Luminova\Sessions\Managers\Cookie or Luminova\Sessions\Managers\Session.

public getManager(): ?\Luminova\Interface\SessionManagerInterface

Return Value:

\Luminova\Interface\SessionManagerInterface|null - Return the current session manager instance, or null if not set.

getStorage

Retrieves the current session storage name.

This method returns the current storage name used to store session data.

public getStorage(): string

Return Value:

string - Return the current storage name.

getName

Retrieves the session cookie name.

This method returns the name of the session cookie used for session management.If a custom cookie name is set in the configuration, it will be returned; otherwise, the default PHP session name is used.

public getName(): string

Return Value:

string - Return the session cookie name.

getResult

Retrieves all session data in the specified format.

public getResult(string $format = 'array'): array|object

Parameters:

Return Value:

array|object - Return the stored session data in the requested format.

get

Retrieves a value from the session storage.

public get(string $key, mixed $default = null): mixed

Parameters:

Return Value:

mixed - Returns the retrieved session data or the default value if not found.

getFrom

Retrieves a session data from a specific session storage name.

public getFrom(string $storage, string $key): mixed

Parameters:

Return Value:

mixed - Returns the retrieved session data or null if not found.

getId

Retrieves the PHP session identifier.

This method returns the active PHP session ID, which uniquely identifiesthe session within the server.

public getId(): string

Return Value:

string - Return the current PHP session identifier.

getIp

Retrieves the IP address associated with the session.

public getIp(): ?string

Return Value:

string|null - Return the stored IP address or null if not set.

getUserAgent

Retrieves the user agent associated with the session.

This method returns the browser or client identifier used when the session was created.

public getUserAgent(): ?string

Return Value:

string|null - Return the user agent string or null if not set.

getToken

Retrieves the client's online session login token.

This method returns a randomly generated token when synchronize() is called.The returned token can be used to track the online session state, validate session integrity or prevent session fixation attacks.

public getToken(): ?string

Return Value:

string|null - Return the login session token, or null if not logged in.

getDatetime

Retrieves the client login session date and time in ISO 8601 format.

The session datetime is generated automatically when synchronize() is called, marking the moment the session login was established.

public getDatetime(): string

Return Value:

string - Return the session login datetime in ISO 8601 format, or null if not logged in.

getTimestamp

Retrieves the client login session creation timestamp.

The session timestamp is generated automatically when synchronize() is called,marking the moment the session login was established.

public getTimestamp(): int

Return Value:

int - Return he Unix timestamp when the session was created.

getExpiration

Retrieves the session expiration timestamp.

This method returns the Unix timestamp at which the session is set to expire.

public getExpiration(): int

Return Value:

int - Return the expiration timestamp or 0 if not set.

getMeta

Retrieves session login metadata key value from session storage.

public getMeta(string $key, ?string $storage = null): mixed

Parameters:

Return Value:

mixed - Return the metadata value or null if not exist.

getMetadata

Retrieves session login metadata information from session storage.

public getMetadata(?string $storage = null): array<string,mixed>

Parameters:

Return Value:

array<string,mixed> - Return an associative array containing session metadata.

getFingerprint

Retrieves the session fingerprint.

The fingerprint is a unique identifier used to track session consistency.

public getFingerprint(): ?string

Return Value:

string|null - Return the session fingerprint or null if not set.

getIpChanges

Retrieves a list of IP address changes during the session.

This method returns an array of previously recorded IP addresses if they changedduring the session lifetime.

public getIpChanges(): array<int,string>

Return Value:

array<int,string> - Return the list of IP address changes.

setHandler

Sets the session save handler responsible for managing session storage.

This method allows specifying a custom session save handler, such as a database array-handler,or filesystem-based handler, to control how session data is stored and retrieved.

The session save handler can be either:

• Luminova\Sessions\Handlers\Database: Stores session data in a database.
• Luminova\Sessions\Handlers\Filesystem: Saves session data in files.
• Luminova\Sessions\Handlers\ArrayHandler: Stores session data temporarily in an array.

public setHandler(Luminova\Base\BaseSessionHandler $handler): self

Parameters:

Return Value:

static - Returns the instance of session class.

Reference

For more details on session handlers, refer to the following documentation:

• Database Session Handler – Stores session data in a database for persistent storage.
• Filesystem Session Handler – Saves session data in files on the server.
• Abstract Base Session Handler – Provides a common interface for custom session handlers.

Example

Using the database handler:

use Luminova\Sessions\Handlers\Database;

$session->setHandler(new Database('tableName'));

Using the filesystem handler:

use Luminova\Sessions\Handlers\Filesystem;

$session->setHandler(new Filesystem('/writeable/session/'));

setManager

Sets the session manager that controls the underlying storage engine for session data.

Unlike a session handler setHandler(), which is only applicable when using Luminova\Sessions\Managers\Session, this method allows specifying a session manager to determine where session data is stored.

The session manager can be either:

• Luminova\Sessions\Managers\Cookie: Stores session data securely in client-side cookies.
• Luminova\Sessions\Managers\Session: Uses PHP's default $_SESSION storage.

public setManager(\Luminova\Interface\SessionManagerInterface $manager): self

Parameters:

Return Value:

self - Returns the instance of session class.

setStorage

Sets the storage name for storing and retrieving session data.

This method allows you to define or override the session name under which session data will be managed.

public setStorage(string $storage): self

Parameters:

Return Value:

self - Returns the instance of session class.

set

Sets a value in the session storage by key.

This method saves or updates a value in the session using the specified key.If the key already exists, its value will be overwritten with the new value.

public set(string $key, mixed $value): self

Parameters:

Return Value:

self - Returns the instance of session class.

setTo

Stores a value in a specific session storage name.

public setTo(string $key, mixed $value, string $storage): self

Parameters:

Return Value:

self - Returns the instance of session class.

Similar:

This method is similar to using setStorage except that it will change the entire storage of current session instance.

$session->setStorage('new-storage')->set('foo', 'bar');

To prevent that behavior, clone the main storage name and restore it afterwards:

$mainStorage = $session->getStorage(); // Main storage name
$session->setStorage('new-storage')
    ->set('foo', 'bar')
    ->setStorage($mainStorage); // Restore the main storage

add

Adds a value to the session storage without overwriting existing keys.

This method will attempts to add a new key-value pair to the session.If the specified key already exists in the session storage, the method does not modify the value and sets the status to false. Otherwise, it adds the new key-value pair and sets the status to true.

public add(string $key, mixed $value, bool &$status = false): self

Parameters:

Return Value:

self - Returns the instance of session class.

put

Queues multiple items for batch storage when save is called.

This method allows adding multiple key-value pairs to a temporary stack, which can later be saved to session storage using $session->save(). If a key already exists in the stack or storage, its value will be overwritten.

public put(string $key, mixed $value): self

Parameters:

Return Value:

self - Returns the instance of session class.

save

Saves all stacked items to the session storage.

This method moves all previously stacked items (added via put()) to session storage. If a storage name is provided, the items are saved under that specific session storage. Once saved, the stack is cleared.

public save(?string $storage = null): bool

Parameters:

Return Value:

bool - Returns true if data was successfully saved, otherwise false.

commit

Commits the current session data.

This method finalizes the session write process by committing any changes made to the session data. Once committed, the session is considered closed and cannot be modified until restarted.

public commit(): void

dequeue

Clears all stacked session data without saving.

This method removes all temporarily stored session data before it is saved. Use it if you want to discard changes before calling save().

public dequeue(): true

Return Value:

true - Always return true.

online

Determines if the client has successfully logged in.

This method verifies whether the synchronize() method has been called, meaning the session user is considered online. It optionally checks a specific session storage; otherwise, it defaults to the current storage.

public online(?string $storage = null): bool

Parameters:

Return Value:

bool - Returns true if the session user is online, false otherwise.

is

Checks if the current session status matches the given status.

Available Status:

• self::DISABLED (PHP_SESSION_DISABLED): Sessions are disabled.
• self::NONE (PHP_SESSION_NONE): Sessions are enabled but no session exists.
• self::ACTIVE (PHP_SESSION_ACTIVE): A session is currently active.

public static is(int $sessionStatus = self::ACTIVE): bool 

Parameters:

Return Value:

bool - Returns true if the current session status matches the given status, otherwise false.

isOnline

Checks if the session user is currently online.

This method acts as an alias for online(), maintaining naming consistency.

public isOnline(): bool

Return Value:

bool - Returns true if the session user is online, false otherwise.

isExpired

Checks if the session is still valid based on elapsed time.

This method determines whether the session has expired based on the last recorded online time. By default, a session is considered expired after 3600 seconds (1 hour).

public isExpired(int $seconds = 3600): bool

Parameters:

Return Value:

bool - Returns true if the session is still valid, false if it has expired.

isStrictIp

Checks if strict IP validation is enabled in the session configuration.

public isStrictIp(): bool

Return Value:

bool -Returns true if strict session IP enforcement is enabled, false otherwise.

isSessionIp

Validates whether the session IP remains unchanged when strict IP enforcement is enabled.

This method ensures that the user's IP address matches the stored session IP, preventing session hijacking if strict IP validation is enabled.

public isSessionIp(): bool

Return Value:

bool -Returns true if strict IP validation is enabled and the IP is unchanged, false otherwise.

toArray

Retrieves session data as an associative array.

public toArray(?string $key = null): array<string,mixed>

Parameters:

Return Value:

array<string,mixed> - Return the session data as an associative array.

toObject

Retrieves session data as an object.

public toObject(?string $key = null): object

Parameters:

Return Value:

object<string,mixed> - Return the session data as a standard object.

remove

Remove a key from the session storage by passing the key.

public remove(string $key): self

Parameters:

Return Value:

Session - Returns the instance of session class.

clear

Clear all data from session storage by passing the storage name or using the default storage.

public clear(?string $storage = null): self

Parameters:

Return Value:

Session - Returns the instance of session class.

has

Check if item key exists in session storage.

public has(string $key): bool

Parameters:

Return Value:

bool - Return true if key exists in session storage else false.

attempt

Tracks the number of session login attempts.

This method increments the number of session login attempts unless reset is requested.The attempt count is stored in session metadata.

Tracks the number of session login attempts.

public attempt(bool $reset = false): true

Parameters:

Return Value:

true - Always returns true.

attempts

Retrieves the number of session login attempts.

public attempts(): int

Return Value:

int - Return the number of recorded login attempts.

regenerate

Regenerate session identifier and delete the old ID associated session file.

public regenerate(): string|bool

Return Value:

string|bool - Return the new generated session Id on success, otherwise false.

start

Initializes PHP session configurations and starts the session if it isn't already started.

This method replaces the default PHP session_start(), with additional configuration and security implementations.

public start(?string $sessionId = null): void

Parameters:

Throws:

• \Luminova\Exceptions\RuntimeException - If an invalid session ID is provided.

Example:

Starting a session with a specified session ID:

To start a session, simply call the start() method. It initializes the session if it's not already started.

namespace App;

use Luminova\Core\CoreApplication;
use Luminova\Sessions\Session;

class Application extends CoreApplication
{
    protected ?Session $session = null;
    protected function onCreate(): void 
    {
        $this->session = new Session();
        $this->session->start('optional_session_id');
    }
}

synchronize

Starts a user's online login session and synchronizes session data.

This method is called once after a successful login to initialize and persist session-related data, marking the user as logged in. If strict IP validation is enabled, it associates the session with a specific IP address. Session data is synchronized and stored using the configured session manager and save handler.

public synchronize(?string $ip = null): bool

Parameters:

Return Value:

bool - Returns true if session login was started, otherwise false.

Throws:

• \Luminova\Exceptions\LogicException - If strict IP validation is disabled and IP address is provided.

Example:

Synchronizing user login session:

namespace App\Controllers\Http;

use Luminova\Base\BaseController;
class AdminController extends BaseController
{
    public function loginAction(): int 
    {
        if($this->app->session->online()){
            return response()->json(['success' => true]);
        }

        $username = $this->request->getPost('username');
        $password = $this->request->getPost('password');

        if($username === 'admin' && $password === 'password'){
            $this->app->session->set('username', $username);
            $this->app->session->set('email', '[email protected]');
            $this->app->session->synchronize();
            return response()->json(['success' => true]);
        }

        return response()->json(['success' => false, 'error' => 'Invalid credentials']);
    }
}

login

Logs in the user by synchronizing session login metadata.

This method serves as an alias for synchronize(), which initializes and maintains the session state after a successful login. If IP validation is enabled, the session will be linked to the provided IP address.

public login(?string $ip = null): bool

Parameters:

Return Value:

bool - Returns true if the session was successfully started, otherwise false.

terminate

Terminates the user's online session and clears session metadata.

This method removes only the session's online status and metadata, ensuring the user is logged out.It does not delete any stored session data but forces the application to recognize the session as inactive.If strict session IP validation is enabled, the associated IP address will also be removed.

public terminate(): bool

Return Value:

bool - Returns true if session was terminated.

logout

Logs out the user by terminating the session login metadata.

This method acts as an alias for terminate(), ensuring the session metadata is cleared and marking the user as logged out. The session data itself remains intact, but the session state will no longer be recognized as active.

public logout(): bool

Return Value:

bool - Returns true if the session was successfully terminated, otherwise false.

destroy

Deletes session data stored in the session table $tableIndex, based on the active session configuration or the table set via setTable in the session manager.

If $allSessions is true, all session and cookie data for the application will be cleared.

public destroy(bool $allSessions = false): bool

Parameters:

Return Value

bool - Returns true if the session data was successfully cleared; false otherwise.

ipChanged

Checks if the user's IP address has changed since the last login session.

public ipChanged(?string $storage = null): bool

Parameters:

Return Value:

bool - Returns false if the user's IP address matches the session login IP, otherwise returns true.

onIpChanged

IP Address Change Listener to detect and respond to user IP changes.

This method monitors the user's IP address during a session and $strictSessionIp is enabled. If the IP address changes,the specified callback is executed. Based on the callback's return value:

• true: The session is terminate the client login session.
• false: The session remains active, allowing manual handling what happens on IP change event.

public onIpChanged(callable $onChange): self

Parameters:

Return Value:

self - Returns the current Session instance.

Example

Session IP address change event:

namespace App;
use Luminova\Core\CoreApplication;
use Luminova\Sessions\Session;

class Application extends CoreApplication
{
    protected ?Session $session = null;

    protected function onCreate(): void 
    {
        $this->session = new Session();
        $this->session->start();
        $this->session->onIpChanged(function (Session $instance, string $sessionIp, array $ipChanges): bool {
            // Handle the IP address change event manually
            // Destroy the session, or return false to keep it or indication that it been handled
            return true; 
        });
    }
}