Environment Bootstrap
The first step of the APPNETOS system bootstrap establishes filesystem paths and loads the protected runtime environment settings used by subsequent bootstrap components.
Purpose and Execution
Bootstrap\Environment\EnvironmentBootstrap is executed first by
SystemBootstrap::boot(). Its boot() method defines the APPNETOS path constants
and then resolves, validates, and defines the environment constants.
APPNETOS_ROOT must already be defined before this step runs.
public function boot(): void
{
$this->definePathConstants();
$this->defineEnvConstants();
}
This bootstrap belongs to the protected startup chain and cannot be replaced through the APPNETOS class extension system.
Environment Configuration
Environment settings are defined in a PHP file at APPNETOS_ROOT/.env.php.
The file must return an associative array. The following example contains all three supported settings:
<?php
return [
'appnetos_environment' => 'docker',
'appnetos_secret' => 'YOUR_UNIQUE_GENERATED_SECRET',
'appnetos_debug' => true,
];
The Bash installer provided by the APPNETOS Docker environment requires
.env.php to exist before installation. Without this file, the installer cannot
determine the selected environment and copy the appropriate configuration files.
Create and configure .env.php before running the installer.
1. appnetos_environment
Type: string ·
Runtime constant: APPNETOS_ENVIRONMENT
Identifies the selected runtime environment and controls whether APPNETOS looks for an additional
environment-specific configuration file. For example, the value docker causes APPNETOS
to check for APPNETOS_ROOT/.env.docker.php.
'appnetos_environment' => 'docker',
The identifier may be empty or contain only ASCII letters (A-Z, a-z),
digits (0-9), underscores (_), and hyphens (-).
An empty identifier skips the environment-specific file lookup.
Names such as docker, development, staging, and
production are examples, not a fixed list of predefined environments.
2. appnetos_secret
Type: string ·
Runtime constant: APPNETOS_SECRET
Provides an installation-specific secret to subsequent runtime components. The environment bootstrap
itself does not perform cryptographic operations with this value: it verifies that the secret is a
non-empty string and exposes it through the APPNETOS_SECRET constant. Its concrete
security-related uses depend on the components that consume the constant.
'appnetos_secret' => 'YOUR_UNIQUE_GENERATED_SECRET',
Use a long, cryptographically random, installation-specific value. The current bootstrap checks only that the value is a non-empty string; it does not enforce a minimum length or entropy. Do not publish or commit active secrets to a public repository.
3. appnetos_debug
Type: bool ·
Runtime constant: APPNETOS_DEBUG
Controls the global APPNETOS debug mode. When enabled, debug-specific runtime behavior can be activated, including the APPNETOS DebugBar and its available diagnostic collectors. Disable debug mode in production environments.
'appnetos_debug' => true,
Valid values are the PHP booleans true and false, not strings such as
'true' or 'false'.
Debug mode is configured at the environment bootstrap level, not through an application or its platform configuration. The normal APPNETOS application configuration and class extension mechanisms cannot enable it. Change the selected environment configuration file to change the setting for a subsequent runtime startup.
Configuration Loading and Replacement
The environment bootstrap resolves its configuration in this order:
- Load
APPNETOS_ROOT/.env.php, if it exists. - Read
appnetos_environmentfrom that default file. - If the value is non-empty, validate its format and look for
APPNETOS_ROOT/.env.<environment>.php. - If the environment-specific file exists, load it and replace the complete configuration array.
- Validate the final values and define the runtime constants.
No configuration merge occurs. Values omitted from an environment-specific file are
not inherited from .env.php. If no matching environment-specific file exists, the
default configuration remains active.
Example: full replacement
Default file, .env.php:
<?php
return [
'appnetos_environment' => 'docker',
'appnetos_secret' => 'DEFAULT_SECRET',
'appnetos_debug' => false,
];
Environment-specific file, .env.docker.php:
<?php
return [
'appnetos_environment' => 'docker',
'appnetos_secret' => 'DOCKER_SECRET',
'appnetos_debug' => true,
];
The final values are docker, DOCKER_SECRET, and true.
The original secret and debug flag are not merged into the replacement array.
A .env.docker.php file containing only appnetos_debug will not inherit
appnetos_secret from .env.php. The required secret will be missing,
and environment initialization will fail. Include all required settings in the replacement file.
The environment-specific filename is selected using the value in the default file. The final
APPNETOS_ENVIRONMENT constant, however, is derived from the final configuration array.
Therefore, repeat appnetos_environment in the replacement file to retain the intended
environment identifier.
Runtime Constants
After validation, the bootstrap defines the following environment constants:
| Configuration key | Runtime constant | Fallback if omitted |
|---|---|---|
appnetos_environment |
APPNETOS_ENVIRONMENT |
Empty string |
appnetos_secret |
APPNETOS_SECRET |
Empty string (validation fails) |
appnetos_debug |
APPNETOS_DEBUG |
false |
Before resolving the environment settings, the bootstrap also defines filesystem constants based on
APPNETOS_ROOT:
| Constant | Path relative to APPNETOS_ROOT |
|---|---|
APPNETOS_PLATFORM |
/platform |
APPNETOS_PUBLIC |
/public |
APPNETOS_VAR |
/var |
APPNETOS_CUSTOM |
/custom |
APPNETOS_VENDOR |
/appnetos/vendor |
APPNETOS_SHARED |
/appnetos/shared |
APPNETOS_APP |
/appnetos/app |
APPNETOS_ADMIN |
/appnetos/admin |
Constants are defined only if they are not already defined. PHP constants cannot be reassigned during the normal application runtime. The trusted startup code must therefore not predefine conflicting values.
Validation and Error Handling
The bootstrap throws an exception when:
- An existing environment configuration file does not return an array.
appnetos_environmentis not a string or contains invalid characters.appnetos_secretis not a string or is empty.appnetos_debugis not a PHP boolean.
A missing .env.php is initially treated as an empty configuration by the loader, but
subsequent secret validation fails. A missing optional environment-specific file does not itself
cause an error; the default configuration is used instead.