Components · v2.x

Session

The Session component wraps the native PHP session with a lazy SessionManagerInterface service. The session starts only when it is needed, is stored in var/sessions/ and is saved at the end of the request.

Module

Manager NeoPHP\Component\Session\SessionManager (final)
Interface NeoPHP\Component\Session\SessionManagerInterface
Attribute #[Component(provider: SessionProvider::class)]
Requires nothing
Required by Csrf, Flash, Security

Inject SessionManagerInterface in a service, a command or a controller:

use NeoPHP\Component\Session\SessionManagerInterface;

public function __construct(private SessionManagerInterface $session)
{
}

The module is enabled by default. To disable it in a project, add it to config/config.php (see the Kernel documentation):

NeoPHP\Component\Session\SessionManager::class => false,

It cannot be disabled while Csrf, Flash, Security are enabled.

The public API of the module is its manager and its interface, Contract\, the attributes, the exceptions, the events and the classes documented below. The classes marked @internal are used by the framework only.

Configuration

The session is configured in config/framework/app.yaml. The session cookie also uses the cookie section (see the Cookie documentation).

session:
    name: NEOSESSID
    lifetime: 0
    gc_maxlifetime: 1440
    save_path: '%kernel.root_path%/var/sessions'

cookie:
    path: /
    domain: ~
    secure: auto
    httponly: true
    samesite: Lax
Option Default Description
session.name NEOSESSID name of the session cookie
session.lifetime 0 lifetime of the session cookie in seconds (0 = until the browser is closed)
session.gc_maxlifetime 1440 seconds of inactivity after which the session data can be deleted
session.save_path var/sessions directory of the session files, created when missing
cookie.path, cookie.domain /, ~ path and domain of the session cookie
cookie.secure auto true, false or auto (secure when the request is in HTTPS)
cookie.httponly true hides the session cookie from JavaScript
cookie.samesite Lax Lax, Strict or None

The session always runs with session.use_strict_mode, session.use_cookies and session.use_only_cookies enabled.

Usage

<?php

declare(strict_types=1);

namespace App\Controller;

use NeoPHP\Component\Controller\Contract\AbstractController;
use NeoPHP\Component\Http\Request\Request;
use NeoPHP\Component\Http\Response\Response;

final class LoginController extends AbstractController
{
    public function login(Request $request): Response
    {
        $session = $this->getSession();
        $session->regenerate();
        $session->set('user_id', 42);

        return $this->redirectToRoute('home');
    }

    public function logout(): Response
    {
        $this->getSession()->invalidate();

        return $this->redirectToRoute('home');
    }
}

The service can also be injected anywhere:

<?php

declare(strict_types=1);

namespace App\Service;

use NeoPHP\Component\Session\SessionManagerInterface;

final class Cart
{
    public function __construct(private SessionManagerInterface $session)
    {
    }

    public function add(int $productId): void
    {
        $items = (array) $this->session->get('cart', []);
        $items[] = $productId;
        $this->session->set('cart', $items);
    }
}

Lazy start

  • Writing (set(), regenerate(), invalidate()) starts the session.
  • Reading (get(), has(), all(), remove(), clear()) starts it only when the browser already sent a session cookie; otherwise it returns the default value, so anonymous visitors get no session cookie.
  • A listener on ResponseEvent (priority -200) saves the session at the end of the request, only when the service was used.

Starting the session after the headers were sent throws a SessionException.

Controllers and views

Helper Where Description
getSession(): SessionManagerInterface controllers returns the session (see the Controller documentation)
session(string $key, mixed $default = null) views reads a session value
{% if session('user_id') %}
    <a href="{{ path('logout') }}">Log out</a>
{% endif %}
<?php if ($this->session('user_id')): ?>
    <a href="<?= $this->path('logout') ?>">Log out</a>
<?php endif ?>

API

SessionManagerInterface

NeoPHP\Component\Session\SessionManagerInterface, implemented by NeoPHP\Component\Session\SessionManager.

Method Description
start(): void starts the session (no-op when already started)
isStarted(): bool whether the session is started
getId(): string session id, '' when not started
getName(): string name of the session cookie
get(string $key, mixed $default = null): mixed reads a value
set(string $key, mixed $value): static writes a value
has(string $key): bool whether a key exists
remove(string $key): mixed removes a key and returns its value (null when missing)
all(): array all the values
clear(): static removes all the values
regenerate(bool $destroy = true): static changes the session id, deletes the old data when $destroy is true
invalidate(): static removes all the values and regenerates the id
save(): void writes and closes the session

Other classes

Class Description
SessionManager(array $options = [], bool $previous = false) options: name, lifetime, gc_maxlifetime, save_path, cookie_path, cookie_domain, cookie_secure, cookie_httponly, cookie_samesite; $previous: the request has a session cookie
Provider\SessionProvider builds the manager from framework.app.session and framework.app.cookie
Helper\Event\SessionListener saves the session on ResponseEvent
Exception\SessionException the session cannot be started, its directory cannot be created, or its id cannot be regenerated

Changelog

  • v2.0.1 — Bugfix: regenerate() and invalidate() throw a SessionException when the session id cannot be regenerated (it was ignored, keeping the old id valid).
  • v2.0.0 — SessionManager is the final entry point of the module, declared with #[Component]; SessionManagerInterface replaces Contract\SessionInterface; Contract\AbstractSession is merged into the manager; Helper/Listener is renamed Helper/Event; the internal classes are marked @internal.
  • v1.6.0 — Session configured in app.yaml, lazy start, getSession() in controllers, session() view helper.