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 Authorization adds a simple browser-facing login gate for demo SSE surfaces that keep a long-lived backend connection open.

How it works

A dedicated Google OAuth flow stores the verified account in the session. The demo SSE runtime then checks the existing session key before opening a persistent connection, so anonymous traffic cannot fan out unlimited streams.

Why it matters

This keeps the showcase safe enough for a public demo while still using the existing Semitexa auth/session pipeline instead of inventing a one-off bypass.

Key concepts

Authorization is required: UI label shown on gated demo blocks before login.
Google Account: The identity provider used for the demo authorization gate.
persistent SSE: A long-lived server-sent events connection that stays open after the initial page render.

Google Account

Authorization gate

Authorization is required before the demo can open long-lived SSE connections.

session-backed login

Verified against Semitexa Ultimate 2026.09.19.1020

Google Authorization

Authorization is required for demo SSE blocks that keep a long-lived backend connection open.

How it works

The Google OAuth flow begins with a redirect to the authorization URL, stores a CSRF state token in the session, receives the callback code, exchanges it for an access token, fetches the user profile, and writes a typed identity payload into the session. The #[AsAuthHandler] on GoogleSessionAuthHandler re-hydrates the principal on every subsequent request.

Why this matters

Long-lived SSE streams opened by anonymous traffic are a resource problem. Gating the stream behind an authenticated session means the connection carries a verified identity, and the server can close the stream cleanly if the session expires.

1<?php23declare(strict_types=1);45namespace App\Application\Handler\PayloadHandler\Example;67use Semitexa\Core\Attribute\AsPayloadHandler;8use Semitexa\Core\Contract\TypedHandlerInterface;910#[AsPayloadHandler(payload: \App\Application\Payload\Request\ExamplePayload::class, resource: \App\Application\Resource\Response\PageResource::class)]11final class GoogleSessionAuthHandler implements TypedHandlerInterface12{13    public function handle(\App\Application\Payload\Request\ExamplePayload $payload, \App\Application\Resource\Response\PageResource $resource): \App\Application\Resource\Response\PageResource14    {15        return $resource16            ->withTitle('Example feature')17            ->withSummary('Keep handlers small, declarative, and centered around the payload contract.');18    }19}

<?php

declare(strict_types=1);

namespace App\Application\Handler\PayloadHandler\Example;

use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Contract\TypedHandlerInterface;

#[AsPayloadHandler(payload: \App\Application\Payload\Request\ExamplePayload::class, resource: \App\Application\Resource\Response\PageResource::class)]
final class GoogleSessionAuthHandler implements TypedHandlerInterface
{
    public function handle(\App\Application\Payload\Request\ExamplePayload $payload, \App\Application\Resource\Response\PageResource $resource): \App\Application\Resource\Response\PageResource
    {
        return $resource
            ->withTitle('Example feature')
            ->withSummary('Keep handlers small, declarative, and centered around the payload contract.');
    }
}

1<?php23declare(strict_types=1);45namespace App\Application\Service\Example;67final class GoogleOAuthClient8{9    public function buildSummary(array $input): array10    {11        return [12            'count' => count($input),13            'items' => $input,14        ];15    }16}

<?php

declare(strict_types=1);

namespace App\Application\Service\Example;

final class GoogleOAuthClient
{
    public function buildSummary(array $input): array
    {
        return [
            'count' => count($input),
            'items' => $input,
        ];
    }
}

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

How it works

Why it matters

This keeps the showcase safe enough for a public demo while still using the existing Semitexa auth/session pipeline instead of inventing a one-off bypass.

Key concepts

Authorization is required: UI label shown on gated demo blocks before login.
Google Account: The identity provider used for the demo authorization gate.
persistent SSE: A long-lived server-sent events connection that stays open after the initial page render.