README

Session support for any PHP applications.

Table of Contents

• Getting started
  • Requirements
  • Highlights
• Documentation
  • Create Session
  • Save Handlers
    • PDO MySql Save Handler
    • Null Save Handler
  • Validation
    • Remote Addr Validation
    • Http User Agent Validation
    • Stack Validation
    • Custom Validation
  • Start Session
  • Interacting With Data
  • Interacting With Flash Data
  • Miscellaneous
  • Save Session
  • Session Middleware PSR-15
• Credits

Getting started

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

composer require tobento/service-session

Requirements

• PHP 8.4 or greater

Highlights

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

Documentation

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

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

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

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

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

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<int, ValidationInterface>

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

Before storing or retrieving data from the session, you need to start the session. You might use the 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

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

Works only if the 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

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

Saves and flashing the session data. You might use the Session Middleware PSR-15 to do so.

use Tobento\Service\Session\SessionSaveException;

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

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

• Tobias Strub
• All Contributors