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

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,
];

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'.

Protected debug setting

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:

  1. Load APPNETOS_ROOT/.env.php, if it exists.
  2. Read appnetos_environment from that default file.
  3. If the value is non-empty, validate its format and look for APPNETOS_ROOT/.env.<environment>.php.
  4. If the environment-specific file exists, load it and replace the complete configuration array.
  5. 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.

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_environment is not a string or contains invalid characters.
  • appnetos_secret is not a string or is empty.
  • appnetos_debug is 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.

Next Steps

Previous

Bootstrap Sequence

Explore Bootstrap Sequence

Next

Error Handling

Explore Error Handling