PHPackages                             tobento/service-session - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. tobento/service-session

ActiveLibrary

tobento/service-session
=======================

Session support for PHP applications.

2.0(7mo ago)02113MITPHPPHP >=8.4

Since Nov 27Pushed 7mo ago1 watchersCompare

[ Source](https://github.com/tobento-ch/service-session)[ Packagist](https://packagist.org/packages/tobento/service-session)[ Docs](https://www.tobento.ch)[ RSS](/packages/tobento-service-session/feed)WikiDiscussions 2.x Synced 1mo ago

READMEChangelog (4)Dependencies (10)Versions (6)Used By (3)

Session Service
===============

[](#session-service)

Session support for any PHP applications.

Table of Contents
-----------------

[](#table-of-contents)

- [Getting started](#getting-started)
    - [Requirements](#requirements)
    - [Highlights](#highlights)
- [Documentation](#documentation)
    - [Create Session](#create-session)
    - [Save Handlers](#save-handlers)
        - [PDO MySql Save Handler](#pdo-mysql-save-handler)
        - [Null Save Handler](#null-save-handler)
    - [Validation](#validation)
        - [Remote Addr Validation](#remote-addr-validation)
        - [Http User Agent Validation](#http-user-agent-validation)
        - [Stack Validation](#stack-validation)
        - [Custom Validation](#custom-validation)
    - [Start Session](#start-session)
    - [Interacting With Data](#interacting-with-data)
    - [Interacting With Flash Data](#interacting-with-flash-data)
    - [Miscellaneous](#miscellaneous)
    - [Save Session](#save-session)
    - [Session Middleware PSR-15](#session-middleware-psr-15)
- [Credits](#credits)

---

Getting started
===============

[](#getting-started)

Add the latest version of the Session service project running this command.

```
composer require tobento/service-session

```

Requirements
------------

[](#requirements)

- PHP 8.4 or greater

Highlights
----------

[](#highlights)

- Framework-agnostic, will work with any project
- Decoupled design
- Native Session or Using Save Handlers
- Flashing data
- Session PSR-15 Middleware

Documentation
=============

[](#documentation)

Create Session
--------------

[](#create-session)

```
use Tobento\Service\Session\Session;
use Tobento\Service\Session\SessionInterface;
use Tobento\Service\Session\SaveHandlerInterface;
use Tobento\Service\Session\ValidationInterface;

$session = new Session(
    name: 'sess',
    maxlifetime: 1800,
    cookiePath: '/',
    cookieDomain: '',
    cookieSamesite: 'Strict',
    secure: true,
    httpOnly: true,
    saveHandler: null, // null|SaveHandlerInterface
    validation: null, // null|ValidationInterface
);

var_dump($session instanceof SessionInterface);
// bool(true)
```

If the saveHandler parameter is null, it uses native session.

**Session Factory**

You might use the session factory to create the session.

```
use Tobento\Service\Session\SessionFactory;
use Tobento\Service\Session\SessionFactoryInterface;
use Tobento\Service\Session\SessionInterface;
use Tobento\Service\Session\SaveHandlerInterface;
use Tobento\Service\Session\ValidationInterface;

$sessionFactory = new SessionFactory();

$session = $sessionFactory->createSession('name', [
    'maxlifetime' => 1800,
    'cookiePath' => '/',
    'cookieDomain' => '',
    'cookieSamesite' => 'Strict',
    'secure' => true,
    'httpOnly' => true,
    'saveHandler' => null, // null|SaveHandlerInterface
    'validation' => null, // null|ValidationInterface
]);

var_dump($session instanceof SessionInterface);
// bool(true)
```

Save Handlers
-------------

[](#save-handlers)

### PDO MySql Save Handler

[](#pdo-mysql-save-handler)

You might use the PDO mysql save handler to store session data in the database.

**Database Table**

```
CREATE TABLE `session` (
    `id` varchar(128),
    `data` text,
    `expiry` int(14) UNSIGNED,
     PRIMARY KEY (`id`)
);
```

**Create Save Handler**

```
use Tobento\Service\Session\PdoMySqlSaveHandler;
use Tobento\Service\Session\SaveHandlerInterface;
use PDO;

$pdo = new PDO(
    dsn: 'mysql:host=localhost;dbname=db_name',
    username: 'root',
    password: '',
    options: [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_EMULATE_PREPARES => false,
    ],
);

$saveHandler = new PdoMySqlSaveHandler(
    table: 'session',
    pdo: $pdo
);

var_dump($saveHandler instanceof SaveHandlerInterface);
// bool(true)
```

### Null Save Handler

[](#null-save-handler)

You might use the Null save handler for testing purposes.

```
use Tobento\Service\Session\NullSaveHandler;
use Tobento\Service\Session\SaveHandlerInterface;

$saveHandler = new NullSaveHandler();

var_dump($saveHandler instanceof SaveHandlerInterface);
// bool(true)
```

Validation
----------

[](#validation)

### Remote Addr Validation

[](#remote-addr-validation)

```
use Tobento\Service\Session\RemoteAddrValidation;
use Tobento\Service\Session\ValidationInterface;

$remoteAddr = $_SERVER['REMOTE_ADDR'] ?? null;

// PSR-7
// $remoteAddr = $serverRequest->getServerParams()['REMOTE_ADDR'] ?? null;

$validation = new RemoteAddrValidation(
    remoteAddr: $remoteAddr,
    trustedProxies: ['192.168.1.1'], // or null
    remoteAddrKey: '_session_remoteAddr', // is default
);

var_dump($validation instanceof ValidationInterface);
// bool(true)

var_dump($validation->remoteAddr());
// string(9) "127.0.0.1"

var_dump($validation->trustedProxies());
// array(1) { [0]=> string(11) "192.168.1.1" }
```

### Http User Agent Validation

[](#http-user-agent-validation)

```
use Tobento\Service\Session\HttpUserAgentValidation;
use Tobento\Service\Session\ValidationInterface;

$validation = new HttpUserAgentValidation(
    httpUserAgent: $_SERVER['HTTP_USER_AGENT'] ?? null,
    httpUserAgentKey: '_session_httpUserAgent' // default
);

var_dump($validation instanceof ValidationInterface);
// bool(true)

var_dump($validation->httpUserAgent());
// string(78) "Mozilla/5.0 ..."
```

### Stack Validation

[](#stack-validation)

You may use the Validations::class to procees multiple validations.

```
use Tobento\Service\Session\Validations;
use Tobento\Service\Session\RemoteAddrValidation;
use Tobento\Service\Session\HttpUserAgentValidation;
use Tobento\Service\Session\ValidationInterface;

$validation = new Validations(
    new RemoteAddrValidation($_SERVER['REMOTE_ADDR'] ?? null),
    new HttpUserAgentValidation($_SERVER['HTTP_USER_AGENT'] ?? null),
);

var_dump($validation instanceof ValidationInterface);
// bool(true)

$validations = $validation->validations();
// array
```

### Custom Validation

[](#custom-validation)

You may write your own validation by implementing the ValidationInterface:

```
use Tobento\Service\Session\ValidationInterface;
use Tobento\Service\Session\SessionInterface;
use Tobento\Service\Session\SessionValidationException;

/**
 * ValidationInterface
 */
interface ValidationInterface
{
    /**
     * Process the validation.
     *
     * @param SessionInterface $session
     * @return void
     * @throws SessionValidationException
     */
    public function process(SessionInterface $session): void;
}
```

Start Session
-------------

[](#start-session)

Before storing or retrieving data from the session, you need to start the session. You might use the [Session Middleware PSR-15](#session-middleware-psr-15) to do so.

```
use Tobento\Service\Session\SessionStartException;
use Tobento\Service\Session\SessionExpiredException;
use Tobento\Service\Session\SessionValidationException;

try {
    $session->start();
} catch (SessionStartException $e) {
    // handle
} catch (SessionExpiredException $e) {
    $session->destroy();

    // You might to restart session and regenerate id
    // on the current request.
    $session->start();
    $session->regenerateId();

    // Or you might send a message to the user instead.

} catch (SessionValidationException $e) {
    // handle
}
```

Interacting With Data
---------------------

[](#interacting-with-data)

**set**

Stores data in the session.

```
$session->set('key', 'value');

// using dot notation:
$session->set('meta.color', 'color');
```

**get**

Get data from the session.

```
$value = $session->get('key');

// using dot notation:
$value = $session->get('meta.color');

// using a default value if key does not exist
$value = $session->get('key', 'default');
```

**has**

To determine if an item is present in the session returning a boolean.

```
$has = $session->has('key');

// using dot notation:
$has = $session->has('meta.color');

// using multiple keys.
$has = $session->has('key', 'meta.color');

$has = $session->has(['key', 'meta.color']);
```

**delete**

Delete data from the session.

```
$session->delete('key');

// using dot notation:
$session->delete('meta.color');
```

**deleteAll**

Delete all data from the session.

```
$session->deleteAll();
```

**all**

Get all data from the session.

```
$data = $session->all();
```

Interacting With Flash Data
---------------------------

[](#interacting-with-flash-data)

Works only if the [Save Session](#save-session) method is being called on every request end.

**flash**

Store data in the session for the current and next request.

```
$session->flash('key', 'value');

// using dot notation:
$session->flash('message.success', 'Message');
```

**now**

Store data in the session for the current request.

```
$session->now('key', 'value');

// using dot notation:
$session->now('message.success', 'Message');
```

**once**

Store data in the session. After first retrieving data, the flashed data will be deleted.

```
$session->once('key', 'value');

// using dot notation:
$session->once('message.success', 'Message');
```

Miscellaneous
-------------

[](#miscellaneous)

**regenerateId**

Regenerates new session id. Use it when changing important user states such as log in and logout.

```
$session->regenerateId();
```

**destroy**

Destroys the session altogether but does not regenerate its id.

```
$session->destroy();
```

**name**

Get the session name.

```
$name = $session->name();
```

**id**

Get the session id.

```
$id = $session->id();
```

Save Session
------------

[](#save-session)

Saves and flashing the session data. You might use the [Session Middleware PSR-15](#session-middleware-psr-15) to do so.

```
use Tobento\Service\Session\SessionSaveException;

try {
    $session->save();
} catch (SessionSaveException $e) {
    // handle
}
```

Session Middleware PSR-15
-------------------------

[](#session-middleware-psr-15)

You may use the session middleware, which starts the session, adds the session as request attribute and finally calls the save method to save session data.
Note that the session middleware handles only the SessionExpiredException.
You may handle SessionStartException and SessionValidationException by your application error handling middleware or write your own session middleware fitting your application.

```
use Tobento\Service\Middleware\MiddlewareDispatcher;
use Tobento\Service\Middleware\AutowiringMiddlewareFactory;
use Tobento\Service\Middleware\FallbackHandler;
use Tobento\Service\Container\Container;
use Tobento\Service\Session\Session;
use Tobento\Service\Session\SessionInterface;
use Tobento\Service\Session\Middleware\Session as SessionMiddleware;
use Psr\Http\Server\RequestHandlerInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\ResponseInterface;
use Nyholm\Psr7\Factory\Psr17Factory;

// create middleware dispatcher.
$dispatcher = new MiddlewareDispatcher(
    new FallbackHandler(new Psr17Factory()->createResponse(404)),
    new AutowiringMiddlewareFactory(new Container()) // any PSR-11 container
);

$session = new Session(
    name: 'sess',
    maxlifetime: 1800,
    cookiePath: '/',
    cookieDomain: '',
    cookieSamesite: 'Strict',
    secure: true,
    httpOnly: true,
    saveHandler: null,
    validation: null,
);

$dispatcher->add(function(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface {

    $session = $request->getAttribute(SessionInterface::class);

    var_dump($session instanceof SessionInterface);
    // bool(false)

    return $handler->handle($request);
});

$dispatcher->add(new SessionMiddleware($session));

$dispatcher->add(function(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface {

    $session = $request->getAttribute(SessionInterface::class);

    var_dump($session instanceof SessionInterface);
    // bool(true)

    return $handler->handle($request);
});

$request = new Psr17Factory()->createServerRequest('GET', 'https://example.com');

$response = $dispatcher->handle($request);
```

Credits
=======

[](#credits)

- [Tobias Strub](https://www.tobento.ch)
- [All Contributors](../../contributors)

###  Health Score

44

—

FairBetter than 91% of packages

Maintenance68

Regular maintenance activity

Popularity14

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity71

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~280 days

Recently: every ~222 days

Total

6

Last Release

222d ago

Major Versions

1.x-dev → 2.02025-09-29

PHP version history (2 changes)1.0.0PHP >=8.0

2.0PHP >=8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/055d6a1b5c2384bb179c75ab0b55914231d898fdc4dffeb30770f81200e52206?d=identicon)[TOBENTOch](/maintainers/TOBENTOch)

---

Top Contributors

[![tobento-ch](https://avatars.githubusercontent.com/u/16684832?v=4)](https://github.com/tobento-ch "tobento-ch (10 commits)")

---

Tags

packagesessiontobentosession flash

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tobento-service-session/health.svg)

```
[![Health](https://phpackages.com/badges/tobento-service-session/health.svg)](https://phpackages.com/packages/tobento-service-session)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)