spaze/mysql-session-handler

MySQL session handler for Nette Framework with optionally encrypted storage

v3.2.2 2025-11-23 17:19 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

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

$ composer require spaze/mysql-session-handler

Setup

After installation:

1. Create a table named sessions using SQL in sql/create.sql. The name of the table can be changed in the configuration using the tableName key, like this:

sessionHandler:
    tableName: sessions_table

1. Register the extension in your configuration file (e.g. config.neon):

	extensions:
		sessionHandler: Spaze\Session\DI\MysqlSessionHandlerExtension

Features

• For security reasons, the 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, for example, to add additional columns to the session storage table.
• Multi-master replication-friendly (tested in master-master row-based replication setup).

Encrypted session storage

Follow the guide at spaze/encryption to create and configure 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 unencrypted 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) and for an existing session (when a row is updated), even if there is 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, the user id the session belongs to. See for example this code which 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!