https://github.com/nixphp/session
NixPHP Session Plugin to maintain client data across requests.
https://github.com/nixphp/session
framework nixphp php php8 plugin session
Last synced: about 14 hours ago
JSON representation
NixPHP Session Plugin to maintain client data across requests.
- Host: GitHub
- URL: https://github.com/nixphp/session
- Owner: nixphp
- Created: 2025-05-03T14:33:13.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-02-22T16:59:58.000Z (about 2 months ago)
- Last Synced: 2026-03-05T12:04:02.823Z (about 1 month ago)
- Topics: framework, nixphp, php, php8, plugin, session
- Language: PHP
- Homepage:
- Size: 70.3 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](https://github.com/nixphp/session/actions/workflows/php.yml)
[← Back to NixPHP](https://github.com/nixphp/framework)
---
# 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
```bash
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:
```php
session()->set('user_id', 42);
$userId = session()->get('user_id');
```
To remove a key:
```php
session()->forget('user_id');
```
---
### Flash messages
Use flash messages to store data for the *next* request only (e.g. after a redirect):
```php
session()->flash('success', 'Profile updated.');
```
In the next request, access it using:
```php
getFlash('success')): ?>
= $message ?>
```
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:
```php
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](https://github.com/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:
```php
$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.