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.
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.
An environment-specific session configuration must include all required keys. Values are not inherited from the default file.
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.
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.
Default Isolation and Cookie Names
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
app and admin base
contexts in a shared session scope
Public application and administrative sessions belong to separate security boundaries. Never configure a shared scope that spans those boundaries, even if the applications have different runtime-context names. Use the resolved base context to determine compatibility.
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
Do not add custom configuration files or edits directly to an
application's original directory, including <application>/.files/. Changes there
can
be lost during updates, replacement or reinstallation. Maintain application-specific customizations
in
./custom/ through the APPNETOS customization mechanism. See Application
Customization
and Custom Installation for the CMD and installation workflow.
Session Bootstrap reads the installed runtime configuration from platform/session/.
It does not read the original application templates or the customization source directory.