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

Google signs the user in, then the session stores the selected demo role and re-hydrates it on every request.

Session State

Google sign-in required

Authorization is required to access role switching in this demo.

Google OAuth #[SessionSegment] AuthResult #[AsAuthHandler]

Verified against Semitexa Ultimate 2026.09.19.1020

Session Auth

Authenticate once per session — the framework stores identity and re-hydrates it on every request.

How it works

Google OAuth is the single login path. After the callback completes, the authenticated identity is written into a typed Session Payload. On every subsequent request the auth handler reads that payload back out and reconstructs the principal, so handlers never touch raw session keys.

Why this matters

Session auth in long-running PHP workers is fragile when state leaks across requests. Semitexa isolates session read/write into the execution-scoped tier so each request gets a clean view, and the typed segment guarantees the shape is always valid.

1<?php23declare(strict_types=1);45namespace Semitexa\Demo\Application\Payload\Session;67use Semitexa\Core\Session\Attribute\SessionSegment;89#[SessionSegment('demo_google_auth')]10final class GoogleAuthSessionSegment11{12    private ?string $state = null;13    private ?string $returnTo = null;14    private ?string $demoRole = null;15    private ?string $lastError = null;16    private ?GoogleSessionIdentityPayload $identity = null;1718    public function getState(): ?string19    {20        return $this->state;21    }2223    public function setState(?string $state): void24    {25        $this->state = $state !== null && trim($state) !== '' ? trim($state) : null;26    }2728    public function getReturnTo(): ?string29    {30        return $this->returnTo;31    }3233    public function setReturnTo(?string $returnTo): void34    {35        $this->returnTo = $returnTo !== null && trim($returnTo) !== '' ? trim($returnTo) : null;36    }3738    public function getDemoRole(): ?string39    {40        return $this->demoRole;41    }4243    public function setDemoRole(?string $demoRole): void44    {45        $demoRole = $demoRole !== null ? trim($demoRole) : null;46        $this->demoRole = $demoRole !== null && $demoRole !== '' ? $demoRole : null;47    }4849    public function getLastError(): ?string50    {51        return $this->lastError;52    }5354    public function setLastError(?string $lastError): void55    {56        $lastError = $lastError !== null ? trim($lastError) : null;57        $this->lastError = $lastError !== null && $lastError !== '' ? $lastError : null;58    }5960    public function clearLastError(): void61    {62        $this->lastError = null;63    }6465    public function getIdentity(): ?GoogleSessionIdentityPayload66    {67        return $this->identity;68    }6970    /**71     * @param array<string, mixed>|GoogleSessionIdentityPayload|null $identity72     */73    public function setIdentity(array|GoogleSessionIdentityPayload|null $identity): void74    {75        if ($identity === null) {76            $this->identity = null;77        } elseif ($identity instanceof GoogleSessionIdentityPayload) {78            $this->identity = $identity;79        } else {80            $this->identity = GoogleSessionIdentityPayload::fromArray($identity);81        }82    }8384    public function isAuthenticated(): bool85    {86        return $this->identity !== null87            && $this->identity->getSubjectId() !== ''88            && $this->identity->getEmail() !== '';89    }9091    public function clear(): void92    {93        $this->state = null;94        $this->returnTo = null;95        $this->demoRole = null;96        $this->lastError = null;97        $this->identity = null;98    }99}100

<?php

declare(strict_types=1);

namespace Semitexa\Demo\Application\Payload\Session;

use Semitexa\Core\Session\Attribute\SessionSegment;

#[SessionSegment('demo_google_auth')]
final class GoogleAuthSessionSegment
{
    private ?string $state = null;
    private ?string $returnTo = null;
    private ?string $demoRole = null;
    private ?string $lastError = null;
    private ?GoogleSessionIdentityPayload $identity = null;

    public function getState(): ?string
    {
        return $this->state;
    }

    public function setState(?string $state): void
    {
        $this->state = $state !== null && trim($state) !== '' ? trim($state) : null;
    }

    public function getReturnTo(): ?string
    {
        return $this->returnTo;
    }

    public function setReturnTo(?string $returnTo): void
    {
        $this->returnTo = $returnTo !== null && trim($returnTo) !== '' ? trim($returnTo) : null;
    }

    public function getDemoRole(): ?string
    {
        return $this->demoRole;
    }

    public function setDemoRole(?string $demoRole): void
    {
        $demoRole = $demoRole !== null ? trim($demoRole) : null;
        $this->demoRole = $demoRole !== null && $demoRole !== '' ? $demoRole : null;
    }

    public function getLastError(): ?string
    {
        return $this->lastError;
    }

    public function setLastError(?string $lastError): void
    {
        $lastError = $lastError !== null ? trim($lastError) : null;
        $this->lastError = $lastError !== null && $lastError !== '' ? $lastError : null;
    }

    public function clearLastError(): void
    {
        $this->lastError = null;
    }

    public function getIdentity(): ?GoogleSessionIdentityPayload
    {
        return $this->identity;
    }

    /**
     * @param array<string, mixed>|GoogleSessionIdentityPayload|null $identity
     */
    public function setIdentity(array|GoogleSessionIdentityPayload|null $identity): void
    {
        if ($identity === null) {
            $this->identity = null;
        } elseif ($identity instanceof GoogleSessionIdentityPayload) {
            $this->identity = $identity;
        } else {
            $this->identity = GoogleSessionIdentityPayload::fromArray($identity);
        }
    }

    public function isAuthenticated(): bool
    {
        return $this->identity !== null
            && $this->identity->getSubjectId() !== ''
            && $this->identity->getEmail() !== '';
    }

    public function clear(): void
    {
        $this->state = null;
        $this->returnTo = null;
        $this->demoRole = null;
        $this->lastError = null;
        $this->identity = null;
    }
}

1<?php23declare(strict_types=1);45namespace Semitexa\Demo\Application\Handler\PayloadHandler\Auth;67use Semitexa\Auth\Application\Service\AuthSessionWriter;8use Semitexa\Core\Attribute\AsPayloadHandler;9use Semitexa\Core\Attribute\InjectAsMutable;10use Semitexa\Core\Attribute\InjectAsReadonly;11use Semitexa\Core\Contract\TypedHandlerInterface;12use Semitexa\Core\Http\Response\ResourceResponse;13use Semitexa\Core\Session\SessionInterface;14use Semitexa\Demo\Application\Payload\Request\Auth\GoogleCallbackPayload;15use Semitexa\Demo\Application\Payload\Session\GoogleAuthSessionSegment;16use Semitexa\Demo\Application\Payload\Session\GoogleSessionIdentityPayload;17use Semitexa\Demo\Application\Service\GoogleOAuthClient;1819#[AsPayloadHandler(payload: GoogleCallbackPayload::class, resource: ResourceResponse::class)]20final class GoogleCallbackHandler implements TypedHandlerInterface21{22    private const string PROVIDER = 'google';2324    #[InjectAsMutable]25    protected SessionInterface $session;2627    #[InjectAsReadonly]28    protected GoogleOAuthClient $oauthClient;2930    #[InjectAsReadonly]31    protected AuthSessionWriter $authWriter;3233    public function handle(GoogleCallbackPayload $payload, ResourceResponse $resource): ResourceResponse34    {35        if (!isset($this->session)) {36            throw new \RuntimeException('Session service is required for Google OAuth callback.');37        }3839        $segment = $this->session->getPayload(GoogleAuthSessionSegment::class);40        $expectedState = $segment->getState();41        $returnTo = $this->oauthClient->sanitizeReturnTo($segment->getReturnTo() ?? '/demo/rendering/deferred');4243        if ($payload->getError() !== null) {44            $segment->clear();45            $segment->setReturnTo($returnTo);46            $segment->setLastError($payload->getError());47            $this->session->setPayload($segment);48            $resource->setRedirect('/demo/auth/google?google_error=' . rawurlencode($payload->getError()) . '&return_to=' . rawurlencode($returnTo));49            return $resource;50        }5152        if ($payload->getCode() === null || $payload->getState() === null || $expectedState === null || !hash_equals($expectedState, $payload->getState())) {53            $segment->clear();54            $segment->setReturnTo($returnTo);55            $segment->setLastError('invalid_state');56            $this->session->setPayload($segment);57            $resource->setRedirect('/demo/auth/google?google_error=' . rawurlencode('invalid_state') . '&return_to=' . rawurlencode($returnTo));58            return $resource;59        }6061        try {62            $token = $this->oauthClient->exchangeCodeForToken($payload->getCode());63            $accessToken = is_string($token['access_token'] ?? null) ? trim((string) $token['access_token']) : '';64            if ($accessToken === '') {65                throw new \RuntimeException('Google OAuth token response did not include an access token.');66            }6768            $profile = $this->oauthClient->fetchUserInfo($accessToken);69            $subjectId = is_string($profile['sub'] ?? null) ? trim((string) $profile['sub']) : '';70            $email = is_string($profile['email'] ?? null) ? trim((string) $profile['email']) : '';71            $emailVerified = filter_var($profile['email_verified'] ?? false, FILTER_VALIDATE_BOOL);72            $displayName = is_string($profile['name'] ?? null) && trim((string) $profile['name']) !== ''73                ? trim((string) $profile['name'])74                : ($email !== '' ? $email : 'Google Account');75            $pictureUrl = is_string($profile['picture'] ?? null) ? trim((string) $profile['picture']) : null;76            $hostedDomain = is_string($profile['hd'] ?? null) ? trim((string) $profile['hd']) : null;7778            if ($subjectId === '' || $email === '') {79                throw new \RuntimeException('Google OAuth userinfo response is incomplete.');80            }8182            if (!$emailVerified) {83                throw new \RuntimeException('Google account email must be verified.');84            }8586            if (!$this->oauthClient->isAllowedDomain($hostedDomain, $email)) {87                throw new \RuntimeException('Google account is not in the allowed domain.');88            }89        } catch (\Throwable $e) {90            $segment->clear();91            $segment->setReturnTo($returnTo);92            $segment->setLastError($e->getMessage());93            $this->session->setPayload($segment);94            $resource->setRedirect('/demo/auth/google?google_error=' . rawurlencode($e->getMessage()) . '&return_to=' . rawurlencode($returnTo));95            return $resource;96        }9798        $identity = new GoogleSessionIdentityPayload(99            subjectId: $subjectId,100            email: $email,101            displayName: $displayName,102            emailVerified: $emailVerified,103            pictureUrl: $pictureUrl !== '' ? $pictureUrl : null,104            hostedDomain: $hostedDomain !== '' ? $hostedDomain : null,105        );106107        $segment->setState(null);108        $segment->setReturnTo($returnTo);109        $segment->setIdentity($identity);110        if ($segment->getDemoRole() === null) {111            $segment->setDemoRole('viewer');112        }113        $segment->clearLastError();114        $this->session->setPayload($segment);115116        $role = $segment->getDemoRole();117        $role = is_string($role) ? trim($role) : '';118        $role = in_array($role, ['admin', 'editor', 'viewer'], true) ? $role : 'viewer';119        $segment->setDemoRole($role);120        $this->session->setPayload($segment);121122        $this->authWriter->setAuthenticated(123            $this->session,124            'google:' . $subjectId . ':' . $role,125            self::PROVIDER,126        );127128        $this->session->regenerate();129130        $resource->setRedirect($returnTo);131132        return $resource;133    }134}135

<?php

declare(strict_types=1);

namespace Semitexa\Demo\Application\Handler\PayloadHandler\Auth;

use Semitexa\Auth\Application\Service\AuthSessionWriter;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Attribute\InjectAsMutable;
use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Core\Contract\TypedHandlerInterface;
use Semitexa\Core\Http\Response\ResourceResponse;
use Semitexa\Core\Session\SessionInterface;
use Semitexa\Demo\Application\Payload\Request\Auth\GoogleCallbackPayload;
use Semitexa\Demo\Application\Payload\Session\GoogleAuthSessionSegment;
use Semitexa\Demo\Application\Payload\Session\GoogleSessionIdentityPayload;
use Semitexa\Demo\Application\Service\GoogleOAuthClient;

#[AsPayloadHandler(payload: GoogleCallbackPayload::class, resource: ResourceResponse::class)]
final class GoogleCallbackHandler implements TypedHandlerInterface
{
    private const string PROVIDER = 'google';

    #[InjectAsMutable]
    protected SessionInterface $session;

    #[InjectAsReadonly]
    protected GoogleOAuthClient $oauthClient;

    #[InjectAsReadonly]
    protected AuthSessionWriter $authWriter;

    public function handle(GoogleCallbackPayload $payload, ResourceResponse $resource): ResourceResponse
    {
        if (!isset($this->session)) {
            throw new \RuntimeException('Session service is required for Google OAuth callback.');
        }

        $segment = $this->session->getPayload(GoogleAuthSessionSegment::class);
        $expectedState = $segment->getState();
        $returnTo = $this->oauthClient->sanitizeReturnTo($segment->getReturnTo() ?? '/demo/rendering/deferred');

        if ($payload->getError() !== null) {
            $segment->clear();
            $segment->setReturnTo($returnTo);
            $segment->setLastError($payload->getError());
            $this->session->setPayload($segment);
            $resource->setRedirect('/demo/auth/google?google_error=' . rawurlencode($payload->getError()) . '&return_to=' . rawurlencode($returnTo));
            return $resource;
        }

        if ($payload->getCode() === null || $payload->getState() === null || $expectedState === null || !hash_equals($expectedState, $payload->getState())) {
            $segment->clear();
            $segment->setReturnTo($returnTo);
            $segment->setLastError('invalid_state');
            $this->session->setPayload($segment);
            $resource->setRedirect('/demo/auth/google?google_error=' . rawurlencode('invalid_state') . '&return_to=' . rawurlencode($returnTo));
            return $resource;
        }

        try {
            $token = $this->oauthClient->exchangeCodeForToken($payload->getCode());
            $accessToken = is_string($token['access_token'] ?? null) ? trim((string) $token['access_token']) : '';
            if ($accessToken === '') {
                throw new \RuntimeException('Google OAuth token response did not include an access token.');
            }

            $profile = $this->oauthClient->fetchUserInfo($accessToken);
            $subjectId = is_string($profile['sub'] ?? null) ? trim((string) $profile['sub']) : '';
            $email = is_string($profile['email'] ?? null) ? trim((string) $profile['email']) : '';
            $emailVerified = filter_var($profile['email_verified'] ?? false, FILTER_VALIDATE_BOOL);
            $displayName = is_string($profile['name'] ?? null) && trim((string) $profile['name']) !== ''
                ? trim((string) $profile['name'])
                : ($email !== '' ? $email : 'Google Account');
            $pictureUrl = is_string($profile['picture'] ?? null) ? trim((string) $profile['picture']) : null;
            $hostedDomain = is_string($profile['hd'] ?? null) ? trim((string) $profile['hd']) : null;

            if ($subjectId === '' || $email === '') {
                throw new \RuntimeException('Google OAuth userinfo response is incomplete.');
            }

            if (!$emailVerified) {
                throw new \RuntimeException('Google account email must be verified.');
            }

            if (!$this->oauthClient->isAllowedDomain($hostedDomain, $email)) {
                throw new \RuntimeException('Google account is not in the allowed domain.');
            }
        } catch (\Throwable $e) {
            $segment->clear();
            $segment->setReturnTo($returnTo);
            $segment->setLastError($e->getMessage());
            $this->session->setPayload($segment);
            $resource->setRedirect('/demo/auth/google?google_error=' . rawurlencode($e->getMessage()) . '&return_to=' . rawurlencode($returnTo));
            return $resource;
        }

        $identity = new GoogleSessionIdentityPayload(
            subjectId: $subjectId,
            email: $email,
            displayName: $displayName,
            emailVerified: $emailVerified,
            pictureUrl: $pictureUrl !== '' ? $pictureUrl : null,
            hostedDomain: $hostedDomain !== '' ? $hostedDomain : null,
        );

        $segment->setState(null);
        $segment->setReturnTo($returnTo);
        $segment->setIdentity($identity);
        if ($segment->getDemoRole() === null) {
            $segment->setDemoRole('viewer');
        }
        $segment->clearLastError();
        $this->session->setPayload($segment);

        $role = $segment->getDemoRole();
        $role = is_string($role) ? trim($role) : '';
        $role = in_array($role, ['admin', 'editor', 'viewer'], true) ? $role : 'viewer';
        $segment->setDemoRole($role);
        $this->session->setPayload($segment);

        $this->authWriter->setAuthenticated(
            $this->session,
            'google:' . $subjectId . ':' . $role,
            self::PROVIDER,
        );

        $this->session->regenerate();

        $resource->setRedirect($returnTo);

        return $resource;
    }
}

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');
    }
}

1<?php23declare(strict_types=1);45namespace App\Auth\Session;67final class SessionRoleMatrix8{9    public const ROLES = [10        'admin' => [11            'label' => 'Admin',12            'permissions' => ['products.read', 'products.write', 'users.manage', 'orders.manage', 'settings.manage'],13        ],14        'editor' => [15            'label' => 'Editor',16            'permissions' => ['products.read', 'products.write'],17        ],18        'viewer' => [19            'label' => 'Viewer',20            'permissions' => ['products.read'],21        ],22    ];23}24

<?php

declare(strict_types=1);

namespace App\Auth\Session;

final class SessionRoleMatrix
{
    public const ROLES = [
        'admin' => [
            'label' => 'Admin',
            'permissions' => ['products.read', 'products.write', 'users.manage', 'orders.manage', 'settings.manage'],
        ],
        'editor' => [
            'label' => 'Editor',
            'permissions' => ['products.read', 'products.write'],
        ],
        'viewer' => [
            'label' => 'Viewer',
            'permissions' => ['products.read'],
        ],
    ];
}