Revision: Sat, 04 Feb 2023 12:24:33 GMT

HTTP - Session

The default application skeleton enables session integration by default.

If you need to enable a session in an alternative bundle, require composer package spiral/session and add bootloader Spiral\Bootloader\Http\SessionBootloader into your app.

SessionInterface

A user session can be accessed using context specific object Spiral\Session\SessionInterface:

php
use Spiral\Session\SessionInterface;

// ...

public function index(SessionInterface $session): void
{
    $session->resume();
    dump($session->getID());
}

Note
You are not allowed to store session reference in singleton objects. See the workaround below.

Session Section

By default, you are not allowed to work with session directly, but rather allocate the isolated and named section which provides classing set, get, delete or any different functionality. Use getSection of session object for these purposes:

php
public function index(SessionInterface $session): void
{
    $cart = $session->getSection('cart');

    $cart->set('items', ['my-items']);

    dump($cart->getAll());
}

Session Scope

To simplify the usage of a session in singleton services and controllers, use Spiral\Session\SessionScope. This component is also available via prototype property session. The component can be used within singleton services and always point to an active session context:

php
namespace App\Controller;

use Spiral\Prototype\Traits\PrototypeTrait;

class HomeController
{
    use PrototypeTrait;

    public function index(): void
    {
        dump($this->session->getSection('cart')->getAll());
    }
}

Session Lifecycle

The session will be automatically started on first data access and committed when the request leaves SessionMiddleware. To control the session manually, use methods of Spiral\Session\SessionInterface object.

Note
SessionScope fully implements SessionInterface.

Resume session

To manually resume/create a session:

php
$this->session->resume();

Commit

To manually commit and close a session:

php
$this->session->commit();

Abort

To discard all the changes and close a session:

php
$this->session->abort();

Get Session ID

To get a session ID (only when the session is resumed):

php
dump($this->session->getID());

To check if the session has started:

php
dump($this->session->isStarted());

Destroy

To destroy a session and all the content:

php
$this->session->destroy();

Regenerate ID

To issue a new session ID without affecting the session content:

php
$this->session->regenerateID();

Custom Configuration

To alter session configuration, create file app/config/session.php to change needed values:

php
<?php

declare(strict_types=1);

use Spiral\Core\Container\Autowire;
use Spiral\Session\Handler\FileHandler;

return [
    'lifetime' => 86400,
    'cookie'   => 'sid',
    'secure'   => false,
    'handler'  => new Autowire(
        FileHandler::class,
        [
            'directory' => directory('runtime') . 'session',
            'lifetime'  => 86400
        ]
    )
];

Custom Session Handler

The session component is based on native PHP session implementation. By default, the session content is stored in the file system in the runtime/session directory.

To change the session storage driver, use any SessionHandlerInterface compatible handler.

php
<?php
return [
    'handler' => new Autowire(
        MemoryHandler::class,
        [
            'driver' => 'redis',
            'database' => 1,
            'lifetime'  => 86400
        ]
    )
];

Note
You can use Autowire instead of the class name to configure additional parameters.

Customize Session initialization

The session is initialized using a special factory Spiral\Session\SessionFactoryInterface.

php

namespace Spiral\Session;

interface SessionFactoryInterface
{
    /**
     * @param string $clientSignature User specific token, does not provide full security but
     *                                     hardens session transfer.
     * @param string|null $id When null - expect php to create session automatically.
     */
    public function initSession(string $clientSignature, string $id = null): SessionInterface;
}

You can replace the default implementation of Spiral\Session\SessionFactoryInterface in the container with your own.

php
$container->bindSingleton(\Spiral\Session\SessionFactoryInterface::class, CustomSessionFactory::class);
Edit this page