APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

Session Bootstrap

The sixth bootstrap step resolves an optional shared session scope for the active application and exact runtime context. Applications remain isolated by default; explicitly configured scopes can connect compatible applications.

Purpose and Execution

Bootstrap\Session\SessionBootstrap runs after CORS Bootstrap and before Security Bootstrap. Application Bootstrap has already resolved the active application, runtime context and base context. Session Bootstrap reads the optional configuration for that application and stores its resolved sessionScope in the shared RuntimeState.

Most applications do not ship or require a session configuration. Without one, APPNETOS uses its normal application- and base-context-based isolation. A shared scope is an explicit opt-in for installations that need compatible applications to recognize the same logical session.

public function boot(): void
{
    $application = $this->runtimeState->getApplication();

    if ($application === null || $application === '') {
        $this->runtimeState->setSessionScope('');
        return;
    }

    $session = $this->loadSessionFile($application);
    $contextSession = $session !== [] ? $this->getContextSession($session) : [];

    $this->runtimeState->setSessionScope(
        $contextSession !== [] ? $this->resolveSessionScope($contextSession) : '',
    );
}

Simplified representation of the bootstrap flow. The bootstrap does not start a PHP session, generate session IDs, or create the physical browser cookie name.

Shared Session Scopes

The diagram shows two applications intentionally using the same session scope while administration remains separated by its own base-context security boundary.

APPNETOS session scopes: shop and CMS application contexts share a configured scope, while administration contexts remain isolated by a separate security boundary.
Session sharing is optional and must be limited to compatible applications within the same security boundary.

Configuration File Resolution

Session Bootstrap reads installed runtime definitions from platform/session/, using the application identifier resolved by Application Bootstrap.

platform/session/appnetos-shop.php
platform/session/appnetos-shop.docker.php

When APPNETOS_ENVIRONMENT is docker and the environment-specific file exists, that file is loaded instead of the default file. The arrays are not merged. If the environment-specific file is absent, the default file is considered. If neither exists, the runtime session scope is reset to an empty string.

Complete Example: Shop and CMS

To opt two applications into a common logical session, configure the same scope string for their respective app runtime contexts. Each application has its own installed session configuration file.

Shop: platform/session/appnetos-shop.php

<?php

declare(strict_types=1);

return [
    'application' => 'appnetos-shop',
    'contexts' => [
        'app' => [
            'scope' => 'shop_cms',
        ],
    ],
];

CMS: platform/session/appnetos-cms.php

<?php

declare(strict_types=1);

return [
    'application' => 'appnetos-cms',
    'contexts' => [
        'app' => [
            'scope' => 'shop_cms',
        ],
    ],
];

Both configurations resolve to RuntimeState::getSessionScope() === 'shop_cms' when the respective app context is active. Core\Cookie then uses the scope as the physical cookie-name prefix, and Core\Session uses it as the persisted session application identifier.

Shared scope does not guarantee a shared browser cookie

The browser must actually send the same cookie to both applications. APPNETOS cookies use a default path of /, but the cookie implementation does not set a cross-subdomain Domain attribute. Applications on different hosts therefore do not automatically share cookies. Session persistence, base-context compatibility and browser cookie policies must also align.

Configuration Reference

Key Type Behavior
application string Required non-empty application identifier; must match the resolved application and configuration filename stem.
contexts array Required map of exact runtime-context names to session definitions.
contexts.<context>.scope string Optional. Non-empty values define the shared scope. Missing or blank values retain default isolation.

Application identifier

The identifier must match the current application. A different identifier or a missing application key is rejected.

'application' => 'appnetos-shop',

Exact context lookup

Only contexts[<active-runtime-context>] is consulted. There is no fallback to the application's default_context, to the base_context, or to a special shared context. Omitting a context leaves its default isolation intact.

 'contexts' => [
    'app' => [
        'scope' => 'shop_cms',
    ],
    // 'admin' is not configured: no shared scope for admin.
],

Session scope

Whitespace around the scope is trimmed before validation. Allowed characters are ASCII letters, digits, underscores and hyphens. An empty or whitespace-only value means no shared scope. Other characters are rejected.

 'contexts' => [
    'app' => [
        'scope' => 'shop_cms', // Valid
    ],
],

// Other valid values: 'storefront-1', 'CUSTOMERS_2026'
// Invalid: 'shop cms', 'shop.cms', 'shop/cms' 

The reserved key contexts.shared is explicitly unsupported and causes a bootstrap exception. Define a common scope separately under each application's actual runtime context instead.

When Session Bootstrap resolves no scope, it writes an empty string into RuntimeState. Later, Core\Cookie builds physical cookie names from the application and base context. When a shared scope exists, that scope replaces the application/base-context prefix.

Runtime Session scope Logical key Physical cookie name
DNS Control / admin base context None SESSION APPNETOS_DNS_CONTROL_ADMIN_SESSION
Shop / app shop_cms SESSION SHOP_CMS_SESSION
CMS / app shop_cms SESSION SHOP_CMS_SESSION

Cookie naming is handled by Core\Cookie, not by Session Bootstrap. The same naming rule also applies to other logical cookie keys managed by the core cookie controller. Core\Session uses the scope as its persisted session application identifier when set; persisted session data also records its base context.

Security Boundary: App vs. Admin

A shared scope must be deliberate, limited to mutually trusted applications, and reviewed together with authentication, cookie scope and persistence. It is not a way to bypass authorization or to merge public and administrative identities.

// Safe pattern: shared scope only for compatible app base contexts.
'app' => ['scope' => 'shop_cms'],

// Do NOT reuse 'shop_cms' for any runtime context
// whose base context resolves to 'admin'.

Session Bootstrap validates the configuration's structure and scope syntax. It does not enforce this cross-application security boundary automatically; administrators must ensure the configured scopes are compatible.

Validation and Missing Configuration

Condition Result
No active application or no session file Empty scope; default isolation
No matching runtime-context definition Empty scope; default isolation
Matching context is not an array Empty scope; default isolation
Scope absent, empty or whitespace-only Empty scope; default isolation
Configuration does not return an array Bootstrap exception
Missing or mismatched application, or missing/non-array contexts Bootstrap exception
contexts.shared exists with a non-null value Bootstrap exception
Scope is not a string, or contains invalid characters Bootstrap exception

The scope is resolved at bootstrap time and stored on the existing RuntimeState. Actual session creation, loading, storage and expiration belong to Core\Session later in the lifecycle.

Application Customization and Update Safety

Session Bootstrap reads the installed runtime configuration from platform/session/. It does not read the original application templates or the customization source directory.

Next Steps

Previous

CORS

Explore CORS

Next

Security

Explore Security