Config Model and Settings

This document describes the Config model and how the Light framework manages application configuration through a database-backed key-value storage system with caching support. The Config model provides centralized storage for system settings, feature flags, and runtime configuration that can be modified without code changes.

For information about specific configuration categories like menus, internationalization, and custom fields, see Application Settings, Menu System, Internationalization, and Custom Fields.

---

Config Model Structure

The Config model is a simple database-backed key-value store with three fields:

Field	Type	Purpose
config_id	Int!	Primary key auto-increment identifier
name	String	Configuration key (unique identifier)
value	String	Configuration value (stored as string, can be JSON)

The model extends Light\Model and is exposed through GraphQL with magic field annotations. Configuration values are typically accessed through the static Config::Value() method rather than direct model queries.

Sources: src/Model/Config.php1-28

---

Retrieving Configuration Values

Config::Value() Method

The primary method for retrieving configuration values is the static Config::Value() method, which provides default value fallback:

Behavior:

• Returns the configuration value if the key exists and has a non-null, non-empty value
• Returns the $default parameter if the key doesn't exist or the value is null/empty string
• Returns null if no default is provided and the key is missing or empty

Example usage throughout the codebase:

Sources: src/Model/Config.php15-27 src/App.php476-478 src/App.php605 src/App.php237

---

Configuration Value Flow

Sources: src/Model/Config.php15-27 src/App.php104-119 src/Controller/AppController.php41-57

---

Storing and Updating Configuration

Creating or Updating Config Values

Configuration values are updated through the updateAppConfig or updateAppConfigs GraphQL mutations, which follow this pattern:

GraphQL Mutations

Mutation	Permission Required	Purpose
updateAppConfig(name: String!, value: String!)	config.update	Update single configuration value
updateAppConfigs(data: [ConfigInput!]!)	config.update	Batch update multiple configuration values

The updateAppConfigs mutation also clears the application cache to ensure updated values take effect immediately:

Sources: src/Controller/AppController.php41-72

---

Caching Strategy

Cache Layers

The framework employs a two-tier caching strategy for configuration:

Cache Configuration

The cache lifetime is determined by the mode configuration:

• Development mode (mode = "dev"): 15-second cache lifetime, debug enabled
• Production mode (mode = "prod"): 0-second cache lifetime (no caching), debug disabled

This is configured during App initialization:

Cache Invalidation

When configuration values are updated via updateAppConfigs, the entire cache is cleared:

This ensures that all cached configuration values, GraphQL schemas, and related data are refreshed on the next request.

Sources: src/App.php104-124 src/Controller/AppController.php54

---

Common Configuration Keys

The following table documents frequently-used configuration keys throughout the system:

Config Key	Type	Default	Purpose
mode	String	"dev"	Environment mode ("dev" or "prod") - affects caching and debug output
access_token_expire	Int	900	JWT access token lifetime in seconds (15 minutes)
refresh_token_expire	Int	604800	JWT refresh token lifetime in seconds (7 days)
two_factor_authentication	Boolean	false	Enable/disable TOTP 2FA system-wide
file_manager	Boolean	false	Enable/disable file manager UI and routes
revision	String	""	Comma-separated list of model names to track revisions for
fs	JSON Array	[]	Filesystem adapter configurations (see Filesystem Configuration Management)
menus	JSON Array	[]	Custom menu definitions (see Menu System)
mail_driver	String	null	Email driver: "sendmail", "qmail", "gmail", "smtp"
mail_host	String	null	SMTP host for mail_driver = "smtp"
mail_username	String	null	SMTP username
mail_password	String	null	SMTP password
mail_port	Int	null	SMTP port number
mail_encryption	String	null	SMTP encryption: "tls" or "ssl"
mail_from	String	null	Default "from" email address
mail_from_name	String	null	Default "from" display name
mail_reply_to	String	null	Default "reply-to" email address
mail_reply_to_name	String	null	Default "reply-to" display name

Usage Examples in App Class

Sources: src/App.php476-478 src/App.php594-600 src/App.php789-802 src/App.php602-612 src/App.php695-714 src/App.php586-592 src/App.php233-284

---

JSON-Stored Configuration

Several configuration keys store structured data as JSON strings:

Filesystem Configuration (fs)

Stores an array of filesystem adapter configurations:

The App::getFSConfig() method retrieves this configuration and provides a default local filesystem if none is configured.

Menu Configuration (menus)

Stores custom menu definitions as a nested array structure:

The App::getCustomMenus() method retrieves this configuration and merges it with system default menus from menus.yml.

Sources: src/App.php695-714 src/App.php586-592 src/App.php174-191

---

GraphQL Schema Exposure

The Config model is exposed through GraphQL via the Light\Type\App query interface. The configuration can be queried but is typically accessed indirectly through other App methods:

Direct config manipulation requires appropriate permissions:

• config.update - Required for updateAppConfig and updateAppConfigs mutations
• menu.update - Required for updateAppMenus mutation

Sources: src/Controller/AppController.php37 src/Controller/AppController.php76

---

Best Practices

Using Config::Value() vs Config::Get()

Prefer Config::Value() when:

• You need a simple string value with default fallback
• The config may not exist yet
• You want concise inline retrieval

Use Config::Get() when:

• You need the full model instance
• You're checking for existence before creating
• You need to update the value immediately after reading

Handling Missing Configuration

Always provide sensible defaults for optional configuration:

JSON Configuration Structure

When storing complex data structures in config values:

1. Use json_encode() to store
2. Use json_decode($config->value, true) to retrieve
3. Provide empty array/object defaults: json_decode($config->value ?? "[]", true)
4. Validate structure after decoding to prevent runtime errors

Sources: src/App.php542-544 src/App.php588-591 src/Controller/AppController.php87