System Configuration

Purpose and Scope

This document provides an overview of the configuration management system in the Light framework. The system uses a hybrid multi-source configuration strategy, combining environment variables, database-stored settings, and YAML files to manage different aspects of application behavior.

The Light framework loads configuration from five distinct sources:

1. Environment variables (.env file) for security-sensitive credentials
2. Database-stored settings via the Config model for runtime-configurable values
3. YAML files (permissions.yml, menus.yml) for structural definitions
4. Database schema definition (db.json) for data structure management
5. User-specific preferences stored in the User model

For detailed information about specific configuration areas, see:

• Config Model implementation and database settings: Config Model and Settings
• Common application settings and feature flags: Application Settings
• Menu configuration and management: Menu System
• RBAC role and permission configuration: Role Hierarchy and Permissions
• Database schema management: Database Schema (db.json)

---

Configuration Architecture

The configuration system follows a layered approach where different configuration sources serve specific purposes based on their characteristics:

Configuration Architecture Overview

This diagram shows how configuration flows from various sources through the access layer to application components. The Light\App class orchestrates configuration loading, while Config::Value() provides database-backed settings access, and AppController exposes configuration mutations via GraphQL.

Sources:

• src/Model/Config.php
• src/Controller/AppController.php
• README.md

---

Configuration Sources

Environment Variables (.env)

Environment variables handle security-sensitive credentials that should never be committed to version control. These are loaded from the .env file in the application root directory and accessed via PHP's $_ENV superglobal or getenv().

Variable Pattern	Purpose	Example
DATABASE_*	Database connection parameters	DATABASE_HOSTNAME, DATABASE_DATABASE, DATABASE_USERNAME, DATABASE_PASSWORD, DATABASE_PORT, DATABASE_CHARSET
JWT_SECRET	JWT token signing key	Random string for cryptographic operations
GOOGLE_CLIENT_ID	Google OAuth client identifier	OAuth application credential
OAuth credentials	Social login integration	Microsoft tenant ID, Facebook app ID
Cookie settings	HTTP cookie configuration	Domain, secure flag, partition settings

Database Connection Variables

The following environment variables configure the MySQL database connection used by Light\Db:

DATABASE_HOSTNAME=localhost
DATABASE_DATABASE=my_app
DATABASE_USERNAME=root
DATABASE_PASSWORD=secret
DATABASE_PORT=3306
DATABASE_CHARSET=utf8mb4

These variables are read during application initialization and passed to the Laminas\Db adapter configuration.

JWT Secret

The JWT_SECRET variable provides the cryptographic key for signing and validating JWT tokens. This value must be:

• A random string with high entropy (recommended: 256 bits)
• Unique per deployment environment
• Never exposed in version control or logs

Sources:

• README.md:9-17
• README.md:24-27
• README.md:36-39

---

Config Model (Database)

The Config model src/Model/Config.php provides a database-backed key-value store for runtime-configurable settings. This allows administrators to modify application behavior without code deployment.

Model Structure

The Config model exposes three fields:

Field	Type	Description
config_id	Int!	Auto-increment primary key
name	String	Configuration key (unique)
value	String	Configuration value (stored as text)

Accessing Configuration Values

The static method Config::Value() src/Model/Config.php15-27 provides the primary interface for reading configuration:

This method:

1. Queries the database for a Config record matching $name
2. Returns the value field if found and non-empty
3. Returns $default if the record doesn't exist or has null/empty value
4. Handles null values explicitly to support default fallback

Example Usage Pattern

Sources:

• src/Model/Config.php:1-28

---

YAML Configuration Files

YAML files define structural configurations that typically change only during feature releases and are version-controlled.

permissions.yml

Defines RBAC roles and their associated permissions. This file is loaded by Light\App during initialization and cached for performance. The structure maps role names to arrays of permission strings.

See Role Hierarchy and Permissions for detailed documentation of this file's structure and usage.

menus.yml

Defines the default navigation menu hierarchy, including:

• Menu item labels and icons
• Route paths
• Required permissions for visibility
• Parent-child menu relationships

Menu definitions from this file can be overridden by custom menus stored in Config.menus. See Menu System for details.

Sources:

• High-level architecture diagrams (Diagram 7)

---

Database Schema (db.json)

The db.json file serves as the single source of truth for database schema definitions. This JSON file describes:

• Table structures with columns and data types
• Primary keys and auto-increment settings
• Foreign key relationships and constraints
• Indexes and unique constraints

The schema definition drives:

1. DDL generation via json-to-sql package
2. Schema migration via mysql-schema-migrate package
3. Model code generation via bin/light make:model command

See Database Schema (db.json) for complete documentation of the schema format and usage.

Sources:

• High-level architecture diagrams (Diagram 4)

---

Configuration Access Patterns

Reading Configuration in Application Code

Configuration values are accessed through different patterns depending on the source:

Configuration Access Methods by Layer

This diagram maps application code to the different configuration access patterns available. Environment variables use standard PHP functions, database configs use Config::Value(), and many common settings have dedicated methods in Light\App.

Sources:

• src/Model/Config.php
• src/Controller/AppController.php

---

Configuration via Light\App Methods

The Light\App class src/App.php provides convenience methods that wrap common configuration access patterns:

Method	Returns	Configuration Source
isDev()	bool	Checks if Config.mode == "dev"
getTwoFactorAuth()	bool	Reads Config.enable_two_factor_auth
getAccessTokenExpire()	int	Reads Config.access_token_expire (default: 900 seconds)
getRefreshTokenExpire()	int	Reads Config.refresh_token_expire (default: 604800 seconds)
getMailer()	?PHPMailer	Constructs mailer from SMTP config in database
getIPLocation()	?IPLocation	Returns IP geolocation service instance
getWebAuthn()	WebAuthn	Returns WebAuthn service instance
getCustomMenus()	array	Reads Config.menus JSON array

These methods handle:

• Default value fallback
• Type conversion (string to int/bool)
• Object instantiation from configuration
• Configuration caching

Sources:

• High-level architecture diagrams
• src/Controller/AppController.php

---

Configuration Updates via GraphQL

The AppController src/Controller/AppController.php exposes GraphQL mutations for updating configuration at runtime.

Single Configuration Update

Implementation: src/Controller/AppController.php62-72

The updateAppConfig mutation:

1. Requires @Logged (authenticated user)
2. Requires @Right('config.update') permission
3. Queries for existing Config record by name
4. Creates new Config record if not found
5. Updates the value field
6. Saves to database

Batch Configuration Update

Implementation: src/Controller/AppController.php41-57

The updateAppConfigs mutation:

1. Accepts array of {name, value} objects
2. Processes each configuration item
3. Creates or updates Config records
4. Flushes entire application cache src/Controller/AppController.php54

Cache Invalidation: After updating configurations, the mutation calls $app->getCache()->clear() to ensure cached configuration values are refreshed. This is critical because many components cache configuration reads for performance.

Menu Configuration Update

Implementation: src/Controller/AppController.php80-91

The updateAppMenus mutation:

1. Requires @Right('menu.update') permission
2. Serializes menu array to JSON
3. Stores in Config.menus record
4. Does not flush cache (menu queries read directly from database)

Sources:

• src/Controller/AppController.php:22-150

---

User-Specific Configuration

Individual user preferences are stored in the User model rather than the global Config table:

User Style Preferences

Implementation: src/Controller/AppController.php110-126

Style preferences are stored as JSON in the User.style field. The updateStyle() method merges new values with existing preferences.

User Language Preference

Implementation: src/Controller/AppController.php132-137

Sets the User.language field directly. This affects:

• Translation queries (see Internationalization)
• Date/time formatting
• Number formatting

User Menu Customization

Implementation: src/Controller/AppController.php144-149

Stores custom menu structure in User.menu field as JSON, overriding default menus from menus.yml and Config.menus.

Sources:

• src/Controller/AppController.php:110-149

---

Configuration Hierarchy and Precedence

When multiple configuration sources define the same setting, the system follows this precedence order (highest to lowest):

1. User-specific preferences (User model fields)
2. Database configuration (Config model)
3. Environment variables (.env file)
4. YAML defaults (permissions.yml, menus.yml)
5. Hard-coded defaults (in source code)

Example: Menu system precedence

• User's custom menu (User.menu) overrides
• System custom menus (Config.menus) which overrides
• Default menus (menus.yml)

Example: Token expiration precedence

• Config.access_token_expire overrides
• Hard-coded default (900 seconds)

Sources:

• src/Controller/AppController.php
• High-level architecture diagrams