phpengine/specs/configuration/spec.md

Read this when changing runtime configuration loading, configuration administration, or config-file generation.

Configuration

Purpose

The application loads F3 globals from a runtime configuration file and provides an administrator-only API to read and replace its encoded content with a one-file backup.

Data Model

Artifact	Format	Role
cfg/config.ini.example	Plaintext F3 INI	Tracked template containing placeholders for deployment-specific values.
cfg/config.ini	Plaintext F3 INI	Ignored local configuration copied from the template; it may contain credentials.
cfg/config.bin	base64(gzcompress(ini-text))	Runtime configuration loaded by index.php.
cfg/config.bin.old	Previous config.bin bytes	Single backup created before an administrator save.
config.ini	Plaintext INI	Legacy root-level configuration artifact; not loaded by the application bootstrap.

Business Rules

• Startup must validate PHP 8.5+, require cfg/config.bin, decode it to a temporary file, apply F3 configuration, then remove the temporary file.
• Encrypt()/Decrypt() provide reversible base64+gzip encoding, not secrecy. Treat every configuration artifact as sensitive because it can contain credentials.
• Operators copy cfg/config.ini.example to the ignored cfg/config.ini and provision cfg/config.bin outside the repository; no generation script is tracked.
• Only an authenticated admin may read decoded configuration or save a replacement; save also requires CSRF validation.
• Save first renames config.bin to config.bin.old, writes encoded replacement content, and restores the backup if writing the new file fails.
• The API accepts arbitrary string text; therefore callers must preserve valid F3 INI syntax and required runtime globals. No schema validation exists in the application.

Constants

Constant	Value	Location
AdminController::CONFIGURATION_FILE	cfg/config.bin	src/OpenMind/Api/AdminController.php
AdminController::CONFIGURATION_BACKUP_FILE	cfg/config.bin.old	src/OpenMind/Api/AdminController.php
OMUtils::DEFAULT_SOCKET_TIMEOUT_SECONDS	5	src/OpenMind/System/OMUtils.php

Cross-links

See API routes, encrypted configuration integration, and commands.