Session v5 Documentation

Table of contents

Requirements

  • PHP 7.3+ or 8.0+

Installation 

composer require odan/session

Features

  • PSR-7 and PSR-15 (middleware) support
  • DI container (PSR-11) support
  • Lazy session start
  • PHP 8 support

Usage 

use Odan\Session\PhpSession;

// Create a standard session handler
$session = new PhpSession();

// Set session options before you start the session
// You can use all the standard PHP session configuration options
// https://secure.php.net/manual/en/session.configuration.php

$session->setOptions([
    'name' => 'app',
]);

// Start the session
$session->start();

// Set session value
$session->set('bar', 'foo');

// Get session value
echo $session->get('bar'); // foo

// Commit and close the session
$session->save();

Methods 

// Get session variable
$foo = $session->get('foo');

// Get session variable or the default value
$bar = $session->get('bar') ?? 'my default value';

// Set session variable
$session->set('bar', 'that');

// Get all session variables
$all = $session->all();

// Delete a session variable
$session->remove('key');

// Clear all session variables
$session->clear();

// Generate a new session ID
$session->regenerateId();

// Clears all session
$session->destroy();

// Get the current session ID
$session->getId();

// Set the session ID
$session->setId('...');

// Get the session name
$session->getName();

// Set the session name
$session->setName('my-app');

// Returns true if the attribute exists
$session->has('foo');

// Sets multiple values at once
$session->replace(['foo' => 'value1', 'bar' => 'value2']);

// Get the number of values.
$session->count();

// Force the session to be saved and closed
$session->save();

// Set session runtime configuration
// All supported keys: http://php.net/manual/en/session.configuration.php
$session->setOptions($options);

// Get session runtime configuration
$session->getOptions();

// Set cookie parameters
$session->setCookieParams(4200, '/', '', false, false);

// Get cookie parameters
$session->getCookieParams();

Flash messages

The library provides its own implementation of Flash messages.

// Get flash object
$flash = $session->getFlash();

// Clear all flash messages
$flash->clear();

// Add flash message
$flash->add('error', 'Login failed');

// Get flash messages
$messages = $flash->get('error');

// Has flash message
$has = $flash->has('error');

// Set all messages
$flash->set('error', ['Message 1', 'Message 2']);

// Gets all flash messages
$messages = $flash->all();

Twig flash messages

Add the Flash instance as global twig variable within the Twig::class container definition:

use Odan\Session\SessionInterface;

// ...

$flash = $container->get(SessionInterface::class)->getFlash();
$twig->getEnvironment()->addGlobal('flash', $flash);

Twig template example:

{% for message in flash.get('error') %}
    <div class="alert alert-danger" role="alert">
        {{ message }}
    </div>
{% endfor %}

SameSite Cookies

A SameSite cookie that tells browser to send the cookie to the server only when the request is made from the same domain of the website.

use Odan\Session\PhpSession;

$session = new PhpSession();

$session->setOptions([
    'name' => 'app',
    // Lax will send the cookie for cross-domain GET requests
    'cookie_samesite' => 'Lax',   
    // Optional: Send cookie only over https
    'cookie_secure' => true,
    // Optional: Additional XSS protection
    // Note: The cookie is not accessible for JavaScript!
    'cookie_httponly' => false,
]);

$session->start();

Read more:

Adapter

PHP Session

  • The default PHP session handler
  • Uses the native PHP session functions

Example:

use Odan\Session\PhpSession;

$session = new PhpSession();

Memory Session

  • Optimized for integration tests (with phpunit)
  • Prevent output buffer issues
  • Run sessions only in memory
use Odan\Session\MemorySession;

$session = new MemorySession();

Slim 4 Integration

Configuration

Add your application-specific settings:

// config/settings.php

return [

    // ...

    'session' => [
        'name' => 'webapp',
        'cache_expire' => 0,
    ],
];

For this example we use the PHP-DI package.

Add the container definitions as follows:

<?php

use Odan\Session\PhpSession;
use Odan\Session\SessionInterface;
use Psr\Container\ContainerInterface;

return [
    // ...

    SessionInterface::class => function (ContainerInterface $container) {
        $settings = $container->get('settings');
        $session = new PhpSession();
        $session->setOptions((array)$settings['session']);

        return $session;
    },
];

Session middleware

Lazy session start

The DI container should (must) never start a session automatically because:

  • The DI container is not responsible for the HTTP context.
  • In some use cases an API call from a REST client generates a session.
  • Only a HTTP middleware or an action handler should start the session.

Register the session middleware for all routes:

use Odan\Session\Middleware\SessionMiddleware;

$app->add(SessionMiddleware::class);

Register middleware for a routing group:

use Odan\Session\Middleware\SessionMiddleware;
use Slim\Routing\RouteCollectorProxy;

// Protect the whole group
$app->group('/admin', function (RouteCollectorProxy $group) {
    // ...
})->add(SessionMiddleware::class);

Register middleware for a single route:

use Odan\Session\Middleware\SessionMiddleware;

$app->post('/example', \App\Action\ExampleAction::class)
    ->add(SessionMiddleware::class);