PHPackages                             phpdot/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. [Caching](/categories/caching)
4. /
5. phpdot/session

ActiveLibrary[Caching](/categories/caching)

phpdot/session
==============

Secure session management with pluggable handlers, flash data, CSRF tokens, and PSR-15 middleware.

v2.1.0(1mo ago)06MITPHPPHP >=8.3

Since Apr 12Pushed 1mo agoCompare

[ Source](https://github.com/phpdot/session)[ Packagist](https://packagist.org/packages/phpdot/session)[ RSS](/packages/phpdot-session/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (10)Versions (4)Used By (0)

phpdot/session
==============

[](#phpdotsession)

Secure session management for PHP. Pluggable storage handlers, flash data, CSRF tokens, and PSR-15 middleware.

No `session_start()`. No `$_SESSION`. No global state. Works with Swoole, RoadRunner, FPM, or any PSR-15 stack.

Install
-------

[](#install)

```
composer require phpdot/session
```

Quick Start
-----------

[](#quick-start)

```
use PHPdot\Session\Handler\FileHandler;
use PHPdot\Session\Middleware\SessionMiddleware;
use PHPdot\Session\SessionConfig;
use PHPdot\Session\SessionManager;

$config  = new SessionConfig(name: 'sid', lifetime: 3600);
$handler = new FileHandler('/tmp/sessions');
$manager = new SessionManager($handler, $config);

// Register as global middleware
$router->middleware(SessionMiddleware::class);
```

Three objects. One middleware. Sessions work.

---

Architecture
------------

[](#architecture)

 ```
graph LR
    subgraph "Per request"
        MW[SessionMiddleware]
        MGR[SessionManager]
        S[Session]
        MW -->|orchestrates| MGR
        MGR -->|creates / loads| S
    end

    CFG[SessionConfig]
    ID[SessionId]
    MGR -->|reads| CFG
    MW -->|reads| CFG
    S -->|holds| ID

    subgraph "Pluggable"
        HANDLER[SessionHandlerInterface]
        SERIAL[SerializerInterface]
    end

    MGR -->|read / write / gc| HANDLER
    MGR -->|encode / decode| SERIAL

    FILE[FileHandler] -.->|implements| HANDLER
    REDIS[RedisHandler] -.->|implements| HANDLER
    ARR[ArrayHandler] -.->|implements| HANDLER
    NULL[NullHandler] -.->|implements| HANDLER

    JSON[JsonSerializer] -.->|implements| SERIAL
    PHPS[PhpSerializer] -.->|implements| SERIAL

    style MW fill:#2d3748,color:#fff
    style MGR fill:#2d3748,color:#fff
    style S fill:#2d3748,color:#fff
    style CFG fill:#4a5568,color:#fff
    style ID fill:#4a5568,color:#fff
    style HANDLER fill:#4a5568,color:#fff
    style SERIAL fill:#4a5568,color:#fff
    style FILE fill:#718096,color:#fff
    style REDIS fill:#718096,color:#fff
    style ARR fill:#718096,color:#fff
    style NULL fill:#718096,color:#fff
    style JSON fill:#718096,color:#fff
    style PHPS fill:#718096,color:#fff
```

      Loading ### Request Lifecycle

[](#request-lifecycle)

 ```
flowchart TD
    A[Request arrives] --> B[Read session cookie]
    B --> C["SessionManager::start(cookieId)"]
    C --> D{Cookie validand exists?}
    D -->|yes| E[Resume:deserialize, rotate flash]
    D -->|no| F[Create new session]
    E --> G[Attach Session torequest attribute]
    F --> G
    G --> H[Application handlerset / get / flash / regenerate]
    H --> I["SessionManager::save()"]
    I --> J[Update lastActivity,age flash, serialize, write]
    J --> K[Add Set-Cookie header]
    K --> L[Response sent]

    style A fill:#2d3748,color:#fff
    style H fill:#4a5568,color:#fff
    style L fill:#276749,color:#fff
```

      Loading ### Package Structure

[](#package-structure)

```
phpdot/contracts/src/Session/        (interfaces — separate package)
├── SessionInterface.php              Public API
├── SessionHandlerInterface.php       Storage backend contract
└── SerializerInterface.php           Encode/decode contract

src/                                  (this package — concrete implementations)
├── Handler/
│   ├── FileHandler.php               File-based with flock()
│   ├── RedisHandler.php              Redis with TTL expiration
│   ├── ArrayHandler.php              In-memory (testing)
│   └── NullHandler.php               No-op (stateless APIs)
│
├── Serializer/
│   ├── JsonSerializer.php            Safe default
│   └── PhpSerializer.php             PHP serialize (no object injection)
│
├── Middleware/
│   └── SessionMiddleware.php         PSR-15 lifecycle manager
│
├── Exception/
│   ├── SessionException.php          Base exception
│   ├── SessionExpiredException.php   Idle timeout
│   ├── SessionReadException.php      Storage read failure
│   └── SessionWriteException.php     Storage write failure
│
├── Session.php                       Mutable session instance
├── SessionManager.php                Lifecycle orchestrator
├── SessionConfig.php                 Immutable configuration
└── SessionId.php                     Cryptographic ID value object

```

---

Session API
-----------

[](#session-api)

### Data Access

[](#data-access)

```
$session->set('user_id', 42);
$session->get('user_id');               // 42
$session->get('missing', 'default');    // 'default'
$session->has('user_id');               // true
$session->remove('user_id');
$session->all();                        // all data as array
$session->clear();                      // remove everything
```

### Flash Data

[](#flash-data)

Flash data lives for exactly one more request, then disappears automatically.

```
// Request 1: set flash
$session->flash('success', 'Profile updated!');

// Request 2: read flash
$session->getFlash('success');    // 'Profile updated!'
$session->hasFlash('success');    // true

// Request 3: gone
$session->getFlash('success');    // null
```

Keep flash data alive for another request:

```
$session->reflash();              // keep ALL flash data
$session->keep(['success']);      // keep specific keys only
```

### CSRF Tokens

[](#csrf-tokens)

```
$token = $session->token();             // get or generate
$token = $session->regenerateToken();   // force new token

// In your form