Runtime Bootstrap
The third bootstrap step creates the shared runtime state, makes it accessible during early startup, and initializes environment and HTTP or process information for the current execution.
Purpose and Execution
Bootstrap\Runtime\RuntimeBootstrap runs after
Error
Handling Bootstrap.
It loads the protected runtime classes, constructs one RuntimeState instance, registers
that instance with RuntimeStateHolder, and then populates the initial state.
public function boot(ProcessInput|null $processInput = null): RuntimeState
{
require_once APPNETOS_ROOT . '/appnetos/shared/src/Bootstrap/Runtime/RuntimeState.php';
require_once APPNETOS_ROOT . '/appnetos/shared/src/Bootstrap/Runtime/RuntimeStateHolder.php';
$runtimeState = new RuntimeState();
RuntimeStateHolder::set($runtimeState);
$this->initEnvironment($runtimeState);
if ($processInput !== null) {
$this->initProcess($runtimeState, $processInput);
return $runtimeState;
}
$this->initHttp($runtimeState);
return $runtimeState;
}
Initialization order matters: the holder receives the shared state before
environment,
process, or HTTP fields are populated. Later bootstrap components progressively update this same
object.
A non-null ProcessInput selects the process branch; otherwise the HTTP branch runs.
RuntimeState — Shared Runtime Information
Bootstrap\Runtime\RuntimeState is a final, mutable container for the
current
APPNETOS startup. Its constructor immediately records the startup microtime and generates a runtime
identifier from 16 cryptographically secure random bytes (32 hexadecimal characters).
All other fields are initialized by the responsible bootstrap layers as startup progresses.
public function __construct()
{
$this->microtimeStart = microtime(true);
$this->runtimeId = bin2hex(random_bytes(16));
}
Stored Runtime Information
| Category | Stored information | Population |
|---|---|---|
| General | Startup microtime, runtime ID, environment, secret, debug state | Constructor and RuntimeBootstrap |
| Applications | Registered applications, application slugs, active application, PHP code origin | Subsequent application resolution |
| Contexts | Context, base context, context slug | Process input or subsequent context resolution |
| HTTP | Host, host with port, port, scheme, original URI, normalized path, path segments | HTTP branch of RuntimeBootstrap |
| Class resolution | Class extensions and class mappings | Subsequent bootstrap components |
| Security and sessions | Resolved security identity and session scope | Subsequent bootstrap components |
| Processes | Process flag, executable, operation, arguments | Process branch of RuntimeBootstrap |
Application Identity and Code Origin
The active application identity is distinct from its PHP code origin. This is important for alias
applications: an application may have its own runtime identity while referencing a separate code
origin.
getOrigin() returns the origin when set, otherwise the active application. Calling
setApplication() clears the previously stored origin.
public function getOrigin(): string|null
{
return $this->origin ?? $this->application;
}
RuntimeState is deliberately mutable, but its final declaration prevents
inheritance-based
replacement of this protected bootstrap state container.
RuntimeStateHolder — Early Global Access
Bootstrap\Runtime\RuntimeStateHolder stores a static reference to the active
RuntimeState. It bridges early bootstrap components and global helpers that cannot yet
use normal dependency resolution. It does not create, validate, or independently resolve runtime
values.
RuntimeStateHolder::set($runtimeState);
// Later in the bootstrap sequence:
$runtimeState = RuntimeStateHolder::get();
$runtimeId = $runtimeState->getRuntimeId();
call RuntimeStateHolder::get() only after
RuntimeBootstrap has registered the state with set(). The holder's
internal
property is initially null, although get() declares a non-null return
type.
The holder references the same mutable object used by subsequent bootstrap components; it is not a snapshot, a second state container, or an independent runtime service.
HTTP Runtime Initialization
Without ProcessInput, RuntimeBootstrap marks the runtime as non-process and initializes
host, scheme, and request-path information from PHP server variables.
Host and Port Resolution
- Use non-empty
$_SERVER['HTTP_HOST'], if available. - Otherwise use
$_SERVER['SERVER_NAME']and appendSERVER_PORTwhen present and scalar. - If neither provides a usable host, retain an empty host.
Host values are trimmed and lowercased. The bootstrap stores the host without port, the host with optional port, and the optional port as separate state values.
HTTP Scheme Resolution
The bootstrap checks for HTTPS indicators in the following order:
HTTP_X_FORWARDED_PROTO(only the first comma-separated value)REQUEST_SCHEMEHTTPS(non-empty and notoff)SERVER_PORTequal to443- Fallback:
http
These checks look for a positive HTTPS indicator. An earlier value of http does not
necessarily prevent a later indicator from selecting https.
HTTP_X_FORWARDED_PROTO is evaluated directly.
Ensure the web server or trusted reverse proxy removes untrusted client-supplied forwarded
headers
and supplies the correct value.
Request URI and Path Segments
The original REQUEST_URI is preserved. Its path component is extracted without the
query
string, and the directory of the active public entry script is removed from the beginning of the
path
when applicable. The resulting path is split into non-empty segments.
SCRIPT_NAME: /appnetos/index.php
REQUEST_URI: /appnetos/docs/core?language=en
Stored request URI: /appnetos/docs/core?language=en
Stored path: /docs/core
Stored segments: ["docs", "core"]
If no usable request URI is provided, the bootstrap defaults to / with an empty segment
list.
Removing the public subdirectory does not alter the preserved original URI.
Process Runtime Initialization
When ProcessInput is supplied, RuntimeBootstrap marks the runtime as a process and
copies
its already resolved input fields into the shared state. The HTTP initialization branch is skipped.
| Runtime field | Source |
|---|---|
| Process flag | true |
| Executable | ProcessInput::getExecutable() |
| Operation | ProcessInput::getOperation() |
| Arguments | ProcessInput::getArguments() |
| Application | ProcessInput::getApplication() |
| Context | ProcessInput::getContext() |
This branch is used for command and worker execution. HTTP-specific values are not initialized here; their fields retain their RuntimeState defaults.
Configuration and Environment
RuntimeBootstrap has no dedicated configuration file. It copies the values already validated and defined by Environment Bootstrap into RuntimeState.
protected function initEnvironment(RuntimeState $runtimeState): void
{
$runtimeState->setEnvironment(APPNETOS_ENVIRONMENT);
$runtimeState->setSecret(APPNETOS_SECRET);
$runtimeState->setDebug(APPNETOS_DEBUG);
}
The runtime state receives these values; it does not reload .env.php or resolve
additional
environment-specific files. Environment configuration remains the responsibility of the first
bootstrap step.
Security and Implementation Boundaries
RuntimeState contains the active
APPNETOS_SECRET and internal bootstrap information. Never serialize or return the
complete state to untrusted clients, and avoid logging secret-bearing state objects.
RuntimeStateisfinaland belongs to the protected bootstrap chain.RuntimeStateHoldermust remain a lightweight static reference, not a second state service.- RuntimeState setters support internal initialization; they are not an application configuration mechanism for changing the protected environment settings.
- Runtime ID generation uses
random_bytes(16)and can raiseRandomExceptionif secure randomness is unavailable. - Host and forwarded-protocol values originate from the HTTP server environment and require trustworthy upstream configuration.