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	Plaintext F3 INI	Source configuration, including globals such as DSN, cache, base URL, and feature values.
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	Minimal root-level configuration artifact; not the source used by the generator script.

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.
• The generator uses cfg/config.ini and refuses to overwrite an existing cfg/config.bin.
• 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.