README

Framework-agnostic PHP session manager with a small, fluent API and pluggable save handlers. Bring your own backend — files, an encrypted cookie, a SQL database (PDO), Redis, Memcache/Memcached, or MongoDB — behind one consistent interface.

Requirements

• PHP 8.1 or later
• Individual adapters may require additional extensions or libraries (see each adapter below).

Installation

composer require initphp/sessions

Quick Start

Bootstrap the facade once with createImmutable(), start the session, then read and write values. With no adapter, PHP's default save handler is used.

require_once 'vendor/autoload.php';

use InitPHP\Sessions\Session;

Session::createImmutable()
    ->start();

Session::set('username', 'admin')
    ->set('mail', 'admin@example.com');

echo Session::get('username', 'Undefined');

Every method is available both statically (Session::set(...)) and on the instance returned by createImmutable() — the two styles are interchangeable. You can keep using $_SESSION directly if you prefer; the facade is a convenience layer, not a replacement.

$_SESSION['username'] = 'admin';
echo $_SESSION['username'] ?? 'Undefined';

The Session API

Reading & writing values

Managing the session lifecycle

Adapters

All adapters implement InitPHP\Sessions\Interfaces\AdapterInterface, which extends PHP's native SessionHandlerInterface. Pass an adapter to createImmutable() and it becomes the session's save handler.

File

Stores sessions as files in a directory you choose, without touching the global session.save_path.

use InitPHP\Sessions\Session;
use InitPHP\Sessions\Adapters\FileAdapter;

$adapter = new FileAdapter([
    'path'   => '/var/www/storage/sessions', // required, writable directory
    'prefix' => 'sess_',                      // optional, default "sess_"
]);

Session::createImmutable($adapter)->start();

Redis

Requires ext-redis. Provide connection details inline, or reuse an existing \Redis instance via the redis option.

use InitPHP\Sessions\Session;
use InitPHP\Sessions\Adapters\RedisAdapter;

$adapter = new RedisAdapter([
    'host'     => '127.0.0.1', // string
    'port'     => 6379,        // int
    'timeout'  => 0,           // float, connect timeout (seconds)
    'password' => null,        // null or string (AUTH)
    'database' => 0,           // int (SELECT)
    'ttl'      => 86400,       // int, key expiry (seconds)
    'prefix'   => 'sess_',     // optional key prefix
]);

// Or reuse an existing client:
// $adapter = new RedisAdapter(['redis' => $existingRedis, 'ttl' => 86400]);

Session::createImmutable($adapter)->start();

PDO

Requires ext-pdo and a driver (MySQL, PostgreSQL, SQLite, ...). Pass an existing PDO instance, or a dsn to let the adapter connect.

use InitPHP\Sessions\Session;
use InitPHP\Sessions\Adapters\PDOAdapter;

$pdo = new PDO('mysql:host=localhost;dbname=test', 'root', '');

$adapter = new PDOAdapter([
    'pdo'           => $pdo,          // or 'dsn' => '...', 'username' => '...', 'password' => '...'
    'table'         => 'sessions',    // required
    'withIPAddress' => false,         // optional: also match the client IP on read/destroy
]);

Session::createImmutable($adapter)->start();

Example table (MySQL):

CREATE TABLE `sessions` (
    `id`              VARCHAR(255) NOT NULL,
    `sess_timestamp`  DATETIME NULL DEFAULT NULL,
    `sess_ip_address` VARCHAR(48) DEFAULT NULL,
    `sess_data`       TEXT NOT NULL,
    PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Cookie

Stores the whole session payload in an encrypted, base64-encoded cookie — no server-side storage. Requires initphp/encryption:

composer require initphp/encryption

use InitPHP\Sessions\Session;
use InitPHP\Sessions\Adapters\CookieAdapter;

$adapter = new CookieAdapter([
    'name'     => 'app_session',     // required
    'key'      => 'your-secret-key', // required, encryption key
    'ttl'      => 86400,             // optional, default 86400
    'secure'   => true,              // optional, HTTPS only (default false)
    'httponly' => true,              // optional, hide from JS (default true)
    'samesite' => 'Lax',             // optional, Lax|Strict|None (default Lax)
]);

Session::createImmutable($adapter)->start();

Memcache / Memcached

Requires ext-memcached (preferred) or ext-memcache. The driver is detected automatically.

use InitPHP\Sessions\Session;
use InitPHP\Sessions\Adapters\MemCacheAdapter;

$adapter = new MemCacheAdapter([
    'host'   => '127.0.0.1', // string
    'port'   => 11211,       // int
    'weight' => 1,           // int
    'raw'    => false,       // bool, binary protocol (Memcached only)
    'prefix' => '',          // optional key prefix
    'ttl'    => 86400,       // int, item expiry (seconds)
]);

Session::createImmutable($adapter)->start();

MongoDB

Requires ext-mongodb.

use InitPHP\Sessions\Session;
use InitPHP\Sessions\Adapters\MongoDBAdapter;

$adapter = new MongoDBAdapter([
    'dsn'        => 'mongodb://127.0.0.1:27017',  // required
    'collection' => 'app.sessions',               // required, "database.collection"
]);

Session::createImmutable($adapter)->start();

Custom Adapters

Extend InitPHP\Sessions\AbstractAdapter and implement read(), write() and destroy(). open(), close() and gc() have sensible defaults you can override:

use InitPHP\Sessions\AbstractAdapter;

final class ArrayAdapter extends AbstractAdapter
{
    /** @var array<string, string> */
    private array $store = [];

    public function read(string $id): string|false
    {
        return $this->store[$id] ?? '';
    }

    public function write(string $id, string $data): bool
    {
        $this->store[$id] = $data;

        return true;
    }

    public function destroy(string $id): bool
    {
        unset($this->store[$id]);

        return true;
    }
}

Error Handling

The package throws a small, predictable set of exceptions, all rooted at InitPHP\Sessions\Exceptions\SessionException:

use InitPHP\Sessions\Exceptions\SessionException;

try {
    Session::createImmutable($adapter)->start();
} catch (SessionException $e) {
    // Covers both lifecycle and adapter failures.
}

Documentation

In-depth, copy-pasteable docs live in docs/.

Quality

composer test     # PHPUnit
composer phpstan  # Static analysis (level 8)
composer cs-check # Coding style (PSR-12)
composer qa       # All of the above

Migrating from initphp/redis-session-handler

The standalone initphp/redis-session-handler package is deprecated in favour of this one. The RedisAdapter here is a superset: TTL support, typed exceptions and the unified Session API.

Before:

$redis = new \InitPHP\Redis\Redis(['host' => '127.0.0.1', 'port' => 6379]);
$handler = new \InitPHP\RedisSessionHandler\Handler($redis);
session_set_save_handler($handler, true);
session_start();

After:

use InitPHP\Sessions\Session;
use InitPHP\Sessions\Adapters\RedisAdapter;

$adapter = new RedisAdapter([
    'host'     => '127.0.0.1',
    'port'     => 6379,
    'database' => 0,
    'ttl'      => 86400,
    'prefix'   => 'sess_',
]);

Session::createImmutable($adapter)->start();

This adapter talks directly to ext-redis (or an existing \Redis instance passed via the redis option), so the initphp/redis wrapper is no longer required. Pass the prefix option if you want to keep the previous sess_ prefix exactly.

Credits

• Muhammet ŞAFAK <info@muhammetsafak.com.tr>

License

Copyright © 2022 MIT License