nixphp/session

NixPHP Session Plugin for storing data across requests.

v0.1.1 2026-02-22 12:45 UTC

Requires

• php: >=8.3
• nixphp/framework: ^0.1.0

Requires (Dev)

• phpunit/php-code-coverage: ^12.1
• phpunit/phpunit: ^12.1

Suggests

• nixphp/database: Install to use the database-backed session storage handler.

MIT

• Flo Knapp

README

← Back to NixPHP

nixphp/session

Simple session management for NixPHP, with flash message support built-in.

This plugin adds a lightweight session layer to your NixPHP app, starts sessions safely in HTTP requests, and exposes helpers so you can store data (including flash messages) without worrying about headers or manual initialization.

🧩 Part of the official NixPHP plugin collection. Install it when you need session persistence, and nothing else.

📦 Features

• Starts PHP sessions automatically (skipping CLI)
• Safeguards cookie params (secure/HttpOnly/SameSite) and regenerates IDs on demand
• Flash message helpers (flash, getFlash)
• session() helper bound in the container
• Optional database-backed storage when nixphp/database is installed
• Registers the migration path so vendor/bin/nix migrate up/down can create the sessions table (requires nixphp/cli)

📥 Installation

composer require nixphp/session

Once installed, the plugin is autoloaded and ready to use. If you install nixphp/database too, it can store sessions in your database table instead of native PHP files.

Usage

Accessing the session

Use the global session() helper to access the session storage:

session()->set('user_id', 42);

$userId = session()->get('user_id');

To remove a key:

session()->forget('user_id');

Flash messages

Use flash messages to store data for the next request only (e.g. after a redirect):

session()->flash('success', 'Profile updated.');

In the next request, access it using:

<?php if ($message = session()->getFlash('success')): ?>
    <p class="success"><?= $message ?></p>
<?php endif; ?>

The message is then automatically removed after it has been read.

🔍 Internals

• Automatically starts session_start() for web requests, with hardened cookie parameters and domain normalization.
• Offers Session::regenerate() so you can refresh the session ID during login flows without touching every request.
• Flash data is stored in a dedicated key and removed after access.
• Registers the session() helper and binds it in the service container.
• Provides DatabaseSessionHandler when the database plugin is configured.
• Registers the migration path with nixphp/database so vendor/bin/nix migrate up/down applies the session table changes.

Configuration

src/config.php exposes the following keys:

return [
    'session' => [
        'storage'             => 'default', // switch to 'database' when using nixphp/database
        'trust_proxy_headers' => false,
        'trusted_proxies'     => [],
        'database_table'      => 'sessions',
    ],
];

To use the database handler:

1. Install nixphp/database and configure its database settings.
2. Update the session config’s storage key to database.
3. Run vendor/bin/nix migrate up (requires nixphp/cli) to apply the migration that creates the sessions table.

🛠 Optional Usage in Controllers

You can also access the session directly from the container:

$session = app()->container()->get(Session::class);

But using the session() helper is the recommended way.

✅ Requirements

• nixphp/framework >= 0.1.0
• nixphp/database >= 0.1.1 when enabling database session storage
• MySQL >= 8.0.19 (required when using the database-backed handler)

📄 License

MIT License.