Feature Guide

A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.

What this does

Semitexa treats session state as a typed contract. We do not allow auth state to spread through $this->session->get('current_user') and other string-key guesses.

How it works

A dedicated class marked with #[SessionSegment] owns the session shape. Handlers read and write that payload through SessionInterface::getPayload() and SessionInterface::setPayload(), while semantic methods such as requireUserId() or clear() live on the payload itself.

Why it matters

This kills one of the most persistent sources of auth drift in PHP apps: invisible session conventions. The contract becomes explicit, reviewable, and refactor-safe instead of hiding behind magic key names and duplicated null checks.

Key concepts

#[SessionSegment]: Declares a typed session payload and binds it to one named session segment.
Session Payload: The explicit DTO-like class that owns one session concern instead of scattering string keys across handlers.
SessionInterface::getPayload(): Typed session access API that hydrates the declared payload instead of returning loose values by string key.
string-key session chaos: The legacy pattern where session contracts exist only as ad hoc names like current_user, auth_user, or user_id.

Session Contract

We ended string-key session chaos

Semitexa does not treat session state as a random key-value bag. If some state matters, it must live in a dedicated Session Payload with a typed shape and meaningful methods.

What usually goes wrong

String keys like current_user, auth_user, or user_id drift across handlers, middleware, and listeners until nobody knows the real contract anymore.
Every caller starts duplicating has/get/null checks because the session shape is implicit and fragile.
Renaming one key becomes a distributed grep problem instead of a refactor-safe code change.

0 magic session keys tolerated

1 typed session contract

100% refactor-safe session access

Legacy Session Mess

Handlers guess keys and patch around nulls

Session reads happen through ad hoc strings, so every caller has to remember both the key names and the failure cases.

The real auth contract lives in tribal knowledge, not in code.

Typed Session Contract

Session state is one explicit payload

A dedicated Session Payload owns the shape, and handlers ask for that payload directly through SessionInterface.

Reviewers can see the contract immediately, and refactors stay local.

Semitexa rule

Session state belongs to a dedicated payload class marked with #[SessionSegment].
Code reads session state through SessionInterface::getPayload(), not arbitrary string keys.
Meaningful methods such as requireUserId() or clear() belong on the payload itself.
If no Session Payload exists for a concern, that concern should not be writing random session keys.

typed session contract no string keys

Verified against Semitexa Ultimate 2026.09.19.1020

Session Payloads

Semitexa treats session state as a typed contract, not as an unstructured key-value dump.

How it works

Every piece of session state belongs to a dedicated class marked with #[SessionSegment]. Handlers read and write session state through SessionInterface::getPayload() and SessionInterface::setPayload(). Arbitrary string key access is not available — if no Session Payload exists for a concern, that concern should not be writing to the session.

Why this matters

String-key sessions rot. Keys drift across handlers, middleware, and listeners until nobody knows the real contract. Renaming one key becomes a distributed grep problem. Typed Session Payloads make the contract reviewable, refactor-safe, and local to a single class.

1<?php23declare(strict_types=1);45namespace App\Handler\Auth;67final class LegacyLoginController8{9    public function __invoke(Request $request, SessionInterface $session): Response10    {11        $user = $this->users->findByEmail($request->input('email'));1213        if ($user === null) {14            return $this->error('Invalid credentials.');15        }1617        if (!$user->passwordMatches($request->input('password'))) {18            return $this->error('Invalid credentials.');19        }2021        $session->set('current_user', $user->getId());22        $session->set('current_user_name', $user->getDisplayName());23        $session->set('auth_stage', 'authenticated');2425        return $this->redirect('/account');26    }27}28

<?php

declare(strict_types=1);

namespace App\Handler\Auth;

final class LegacyLoginController
{
    public function __invoke(Request $request, SessionInterface $session): Response
    {
        $user = $this->users->findByEmail($request->input('email'));

        if ($user === null) {
            return $this->error('Invalid credentials.');
        }

        if (!$user->passwordMatches($request->input('password'))) {
            return $this->error('Invalid credentials.');
        }

        $session->set('current_user', $user->getId());
        $session->set('current_user_name', $user->getDisplayName());
        $session->set('auth_stage', 'authenticated');

        return $this->redirect('/account');
    }
}

1<?php23declare(strict_types=1);45namespace App\Auth\Session;67use Semitexa\Core\Session\Attribute\SessionSegment;89#[SessionSegment('browser_auth')]10final class BrowserSessionSegment11{12    private ?string $userId = null;13    private ?string $displayName = null;1415    public function isGuest(): bool16    {17        return $this->userId === null;18    }1920    public function getUserId(): ?string21    {22        return $this->userId;23    }2425    public function setUserId(?string $userId): void26    {27        $this->userId = $userId;28    }2930    public function requireUserId(): string31    {32        if ($this->userId === null) {33            throw new \LogicException('Session does not contain an authenticated user.');34        }3536        return $this->userId;37    }3839    public function getDisplayName(): ?string40    {41        return $this->displayName;42    }4344    public function setDisplayName(?string $displayName): void45    {46        $this->displayName = $displayName;47    }4849    public function clear(): void50    {51        $this->userId = null;52        $this->displayName = null;53    }54}55

<?php

declare(strict_types=1);

namespace App\Auth\Session;

use Semitexa\Core\Session\Attribute\SessionSegment;

#[SessionSegment('browser_auth')]
final class BrowserSessionSegment
{
    private ?string $userId = null;
    private ?string $displayName = null;

    public function isGuest(): bool
    {
        return $this->userId === null;
    }

    public function getUserId(): ?string
    {
        return $this->userId;
    }

    public function setUserId(?string $userId): void
    {
        $this->userId = $userId;
    }

    public function requireUserId(): string
    {
        if ($this->userId === null) {
            throw new \LogicException('Session does not contain an authenticated user.');
        }

        return $this->userId;
    }

    public function getDisplayName(): ?string
    {
        return $this->displayName;
    }

    public function setDisplayName(?string $displayName): void
    {
        $this->displayName = $displayName;
    }

    public function clear(): void
    {
        $this->userId = null;
        $this->displayName = null;
    }
}

1<?php23declare(strict_types=1);45namespace App\Handler\Auth;67use App\Auth\Session\BrowserSessionSegment;8use App\Payload\Auth\LoginPayload;9use App\Resource\Auth\LoginPageResource;10use App\User\UserRepositoryInterface;11use Semitexa\Core\Attribute\AsPayloadHandler;12use Semitexa\Core\Attribute\InjectAsMutable;13use Semitexa\Core\Attribute\InjectAsReadonly;14use Semitexa\Core\Contract\TypedHandlerInterface;15use Semitexa\Core\Exception\AuthenticationException;16use Semitexa\Core\Session\SessionInterface;1718#[AsPayloadHandler(payload: LoginPayload::class, resource: LoginPageResource::class)]19final class LoginHandler implements TypedHandlerInterface20{21    #[InjectAsReadonly]22    protected UserRepositoryInterface $users;2324    #[InjectAsMutable]25    protected SessionInterface $session;2627    public function handle(LoginPayload $payload, LoginPageResource $resource): LoginPageResource28    {29        $user = $this->users->findByEmail($payload->getEmail());30        if ($user === null) {31            throw new AuthenticationException('Invalid credentials.');32        }3334        $user->assertPasswordMatches($payload->getPassword());3536        $segment = $this->session->getPayload(BrowserSessionSegment::class);37        $segment->setUserId($user->getId());38        $segment->setDisplayName($user->getDisplayName());3940        $this->session->setPayload($segment);41        $this->session->regenerate();4243        return $resource->withSuccess('Signed in. The next request will restore this user from the session cookie.');44    }45}46

<?php

declare(strict_types=1);

namespace App\Handler\Auth;

use App\Auth\Session\BrowserSessionSegment;
use App\Payload\Auth\LoginPayload;
use App\Resource\Auth\LoginPageResource;
use App\User\UserRepositoryInterface;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Attribute\InjectAsMutable;
use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Core\Contract\TypedHandlerInterface;
use Semitexa\Core\Exception\AuthenticationException;
use Semitexa\Core\Session\SessionInterface;

#[AsPayloadHandler(payload: LoginPayload::class, resource: LoginPageResource::class)]
final class LoginHandler implements TypedHandlerInterface
{
    #[InjectAsReadonly]
    protected UserRepositoryInterface $users;

    #[InjectAsMutable]
    protected SessionInterface $session;

    public function handle(LoginPayload $payload, LoginPageResource $resource): LoginPageResource
    {
        $user = $this->users->findByEmail($payload->getEmail());
        if ($user === null) {
            throw new AuthenticationException('Invalid credentials.');
        }

        $user->assertPasswordMatches($payload->getPassword());

        $segment = $this->session->getPayload(BrowserSessionSegment::class);
        $segment->setUserId($user->getId());
        $segment->setDisplayName($user->getDisplayName());

        $this->session->setPayload($segment);
        $this->session->regenerate();

        return $resource->withSuccess('Signed in. The next request will restore this user from the session cookie.');
    }
}

1<?php23declare(strict_types=1);45namespace App\Handler\Auth;67use App\Auth\GooglePrincipal;8use App\Auth\Session\GoogleAuthSessionSegment;9use App\Payload\Auth\SessionAuthPayload;10use App\Resource\Auth\SessionAuthResource;11use Semitexa\Auth\Context\AuthManager;12use Semitexa\Core\Attribute\AsPayloadHandler;13use Semitexa\Core\Attribute\InjectAsMutable;14use Semitexa\Core\Contract\TypedHandlerInterface;15use Semitexa\Core\Session\SessionInterface;1617#[AsPayloadHandler(payload: SessionAuthPayload::class, resource: SessionAuthResource::class)]18final class SessionAuthHandler implements TypedHandlerInterface19{20    #[InjectAsMutable]21    protected SessionInterface $session;2223    public function handle(SessionAuthPayload $payload, SessionAuthResource $resource): SessionAuthResource24    {25        $user = AuthManager::getInstance()->getUser();26        $googleUser = $user instanceof GooglePrincipal ? $user : null;2728        $segment = $this->session->getPayload(GoogleAuthSessionSegment::class);29        if ($googleUser !== null) {30            $segment->setDemoRole($payload->getRole() ?? 'viewer');31            $this->session->setPayload($segment);32            $this->session->regenerate();33        }3435        return $resource->withRole($segment->getDemoRole() ?? 'viewer');36    }37}38

<?php

declare(strict_types=1);

namespace App\Handler\Auth;

use App\Auth\GooglePrincipal;
use App\Auth\Session\GoogleAuthSessionSegment;
use App\Payload\Auth\SessionAuthPayload;
use App\Resource\Auth\SessionAuthResource;
use Semitexa\Auth\Context\AuthManager;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Attribute\InjectAsMutable;
use Semitexa\Core\Contract\TypedHandlerInterface;
use Semitexa\Core\Session\SessionInterface;

#[AsPayloadHandler(payload: SessionAuthPayload::class, resource: SessionAuthResource::class)]
final class SessionAuthHandler implements TypedHandlerInterface
{
    #[InjectAsMutable]
    protected SessionInterface $session;

    public function handle(SessionAuthPayload $payload, SessionAuthResource $resource): SessionAuthResource
    {
        $user = AuthManager::getInstance()->getUser();
        $googleUser = $user instanceof GooglePrincipal ? $user : null;

        $segment = $this->session->getPayload(GoogleAuthSessionSegment::class);
        if ($googleUser !== null) {
            $segment->setDemoRole($payload->getRole() ?? 'viewer');
            $this->session->setPayload($segment);
            $this->session->regenerate();
        }

        return $resource->withRole($segment->getDemoRole() ?? 'viewer');
    }
}

How it works

Why it matters

Key concepts

#[SessionSegment]: Declares a typed session payload and binds it to one named session segment.
Session Payload: The explicit DTO-like class that owns one session concern instead of scattering string keys across handlers.
SessionInterface::getPayload(): Typed session access API that hydrates the declared payload instead of returning loose values by string key.
string-key session chaos: The legacy pattern where session contracts exist only as ad hoc names like current_user, auth_user, or user_id.