spaze/mysql-session-handler

MySQL session handler for Nette Framework with optionally encrypted storage

v3.2.1 2025-08-22 18:21 UTC

Requires

• php: ^8.2
• nette/database: ^3.2.4
• nette/di: ^3.2

Requires (Dev)

• nette/schema: ^1.3
• php-parallel-lint/php-console-highlighter: ^1.0
• php-parallel-lint/php-parallel-lint: ^1.4
• phpstan/phpstan: ^2.1
• phpstan/phpstan-nette: ^2.0
• spaze/coding-standard: ^1.8
• spaze/encryption: ^2.0

Suggests

• spaze/encryption: Adds a support for encrypted session storage

MIT

• Michal Špaček
• Pematon, s.r.o.

README

Custom PHP session handler for Nette Framework that uses MySQL database for storage.

Requirements

• nette/database 3.2+
• nette/di 3.2+
• PHP 8.2+

Installation

Preferred way to install spaze/mysql-session-handler is by using Composer:

$ composer require spaze/mysql-session-handler

Setup

After installation:

1. Create the table sessions using SQL in sql/create.sql.

2. Register an extension in config.neon:

	extensions:
		sessionHandler: Spaze\Session\DI\MysqlSessionHandlerExtension

Features

• For security reasons, Session ID is stored in the database as an SHA-256 hash.
• Supports encrypted session storage via spaze/encryption which uses paragonie/halite which uses Sodium.
• Events that allow you to add additional columns to the session storage table for example.
• Multi-Master Replication friendly (tested in Master-Master row-based replication setup).

Encrypted session storage

Follow the guide at spaze/encryption to define a new encryption key.

Define a new service:

sessionEncryption: \Spaze\Encryption\Symmetric\StaticKey('session', %encryption.keys%, %encryption.activeKeyIds%)

Add the new encryption service to the session handler:

sessionHandler:
    encryptionService: @sessionEncryption

Migration from unecrypted to encrypted session storage is not (yet?) supported.

Events

onBeforeDataWrite

The event occurs before session data is written to the session table, both for a new session (when a new row is inserted) or an existing session (a row is updated), even if there's no change in the session data.

Additional columns

You can add a new column to the session table by calling setAdditionalData() in the event handler:

setAdditionalData(string $key, $value): void

Use it to store for example user id to which the session belongs to. See for example this code that uses the Nette\Security\User::onLoggedIn handler to do that.

Credits

This is heavily based on MySQL Session handler by Pematon (Marián Černý & Peter Knut), thanks!