Application Settings

This document details the specific configuration values that control application behavior, including mode settings, feature flags, token expiration, and branding options. These settings are stored as key-value pairs in the Config model (see Config Model and Settings for storage mechanism details). For menu configuration specifically, see Menu System.

Configuration Architecture

The application uses a key-value configuration system where settings are stored in the Config database table. Configuration values are accessed throughout the codebase using Config::Value(key, default) and cached for performance. The Light\App class reads configuration during initialization to set operational parameters.

Sources: src/App.php59-147 src/Type/App.php1-541

Mode Setting

The mode configuration key controls whether the application runs in development or production mode. This setting affects debugging output, error reporting, and GraphQL schema caching.

Mode	Debug Enabled	Cache Lifetime	Error Details
dev	Yes	15 seconds	Full stack traces
prod	No	0 (permanent)	Minimal messages

The mode is read during Light\App initialization:

The mode value is used in two key locations:

• GraphQL schema caching: Production mode sets cache lifetime to 0 (permanent), development mode uses 15 seconds src/App.php107-119
• Error response formatting: Development mode includes debug messages and stack traces via DebugFlag::INCLUDE_DEBUG_MESSAGE | DebugFlag::INCLUDE_TRACE src/App.php160-164

Configuration:

• Key: mode
• Values: "dev" (default) | "prod"
• Access Method: $app->isDevMode() returns true if not prod mode

Sources: src/App.php51-52 src/App.php107-119 src/App.php160-164 src/App.php581-584 src/Type/App.php179-183

Feature Flags

Feature flags enable or disable specific application functionality. These boolean flags control UI elements, authentication methods, and system features.

Core Feature Flags

Sources: src/App.php174-191 src/App.php475-478 src/App.php594-600 src/App.php789-802 src/Type/App.php287-310

file_manager

Controls whether the File Manager feature is available in the application.

• Key: file_manager
• Type: Boolean
• Default: false (disabled)
• Access Method: $app->isFileManagerEnabled()
• Effect: When enabled, adds a "File Manager" menu item to the application menu with icon sym_o_folder and permission fs src/App.php180-190

revision

Enables the revision tracking and restore system for specific models. The value is a comma-separated list of model class names.

• Key: revision
• Type: String (comma-separated list)
• Default: Empty (no models tracked)
• Access Method: $app->isRevisionEnabled(string $model)
• Effect: When a model is listed, changes to that model are tracked in EventLog and can be restored via RevisionController::restoreRevision() src/App.php789-802

Example configuration value: "User,Role,Config"

two_factor_authentication

Enables TOTP-based two-factor authentication for user logins.

• Key: two_factor_authentication
• Type: Boolean
• Default: false (disabled)
• Access Method: $app->isTwoFactorAuthentication()
• Effect: When enabled, users can set up 2FA secrets and must provide TOTP codes during login src/App.php475-478 src/Type/App.php174-177

webauthn_enabled

Controls whether WebAuthn/biometric authentication is available.

• Key: webauthn_enabled
• Type: Boolean
• Default: true (enabled if library installed)
• Access Method: Type\App::isWebAuthnEnabled()
• Effect: Allows users to register and authenticate using biometric credentials (fingerprint, face recognition, security keys) src/Type/App.php287-290

forget_password_enabled

Enables the password reset flow via email.

• Key: forget_password_enabled
• Type: Boolean
• Default: true (enabled)
• Access Method: Type\App::isForgetPasswordEnabled()
• Effect: Shows "Forgot Password" link on login screen and enables password reset email functionality src/Type/App.php293-297

authentication_password_based

Controls whether traditional username/password authentication is available.

• Key: authentication_password_based
• Type: Boolean
• Default: true (enabled)
• Access Method: Type\App::isPasswordBasedEnabled()
• Effect: Determines if users can log in with username and password. If disabled, only OAuth, WebAuthn, or other authentication methods are available src/Type/App.php305-309

Sources: src/Type/App.php287-309

Token Expiration Settings

JWT token expiration settings control the lifetime of access and refresh tokens used for authentication. These values are critical for security and user experience balance.

Token Configuration Table

Setting Key	Default Value	Purpose	Used In
access_token_expire	900 (15 minutes)	Short-lived token for API access	JWT payload, cookie lifetime
refresh_token_expire	604800 (7 days)	Long-lived token for obtaining new access tokens	Refresh token endpoint

Sources: src/App.php602-612 src/App.php631-685 src/App.php877-920

access_token_expire

Controls the lifetime of access tokens in seconds.

• Key: access_token_expire
• Type: Integer (seconds)
• Default: 900 (15 minutes)
• Access Method: $app->getAccessTokenExpire()
• JWT Field: Sets the exp claim in access tokens src/App.php633-644
• Usage: Access tokens are validated on every GraphQL request via Auth\Service

Security Consideration: Shorter lifetimes improve security by reducing the window of vulnerability if a token is compromised, but require more frequent token refreshes.

refresh_token_expire

Controls the lifetime of refresh tokens in seconds.

• Key: refresh_token_expire
• Type: Integer (seconds)
• Default: 604800 (7 days)
• Access Method: $app->getRefreshTokenExpire()
• JWT Field: Sets the exp claim in refresh tokens src/App.php660-668
• Usage: Refresh tokens are used at the /refresh_token endpoint to obtain new access tokens without re-authentication src/App.php877-920

Token Refresh Flow:

1. Client detects expired access token
2. Client sends request to /refresh_token with refresh token cookie
3. Server validates refresh token JWT and checks jti against UserLog
4. Server issues new access token with same jti
5. Client continues with new access token

Sources: src/App.php602-685 src/App.php877-920

Company Branding Settings

These settings customize the application's visual identity and copyright information displayed in the user interface.

Branding Configuration Table

Setting Key	Default Value	Type	Purpose
company	"HostLink"	String	Company name displayed in UI
company_logo	null	String (URL)	Logo image URL
copyright_year	Current year	String	Copyright year in footer
copyright_name	"HostLink(HK)"	String	Copyright holder name

Sources: src/Type/App.php299-327

company

The primary company name displayed throughout the application.

• Key: company
• Type: String
• Default: "HostLink"
• Access Method: Type\App::getCompany()
• GraphQL Field: getCompany: String!
• Usage: Displayed in application header, login screen, and other branding locations src/Type/App.php299-303

company_logo

URL or path to the company logo image.

• Key: company_logo
• Type: String | null
• Default: null (no logo)
• Access Method: Type\App::getCompanyLogo()
• GraphQL Field: getCompanyLogo: String
• Usage: If set, displayed in application header and login screen src/Type/App.php311-315

copyright_year

The year displayed in copyright notices.

• Key: copyright_year
• Type: String
• Default: Current year via date("Y")
• Access Method: Type\App::getCopyrightYear()
• GraphQL Field: getCopyrightYear: String
• Usage: Displayed in application footer as part of copyright notice src/Type/App.php317-321

copyright_name

The legal entity name for copyright notices.

• Key: copyright_name
• Type: String
• Default: "HostLink(HK)"
• Access Method: Type\App::getCopyrightName()
• GraphQL Field: getCopyrightName: String
• Usage: Displayed in application footer: "© {year} {name}" src/Type/App.php323-327

Sources: src/Type/App.php299-327

Custom Field Configuration

The custom_field_models setting enables runtime schema extension for specific models through the CustomField system.

• Key: custom_field_models
• Type: String (comma-separated list of model names)
• Default: Empty (no models have custom fields)
• Access Method: Type\App::getCustomFieldModels()
• Effect:
  • Models listed in this setting can have custom fields defined at runtime via the CustomField model
  • A "Custom Field" menu item appears in the application menu if this config is set src/Type/App.php82-89 src/Type/App.php211-215
  • The getCustomFieldSchema(model) query returns FormKit schema for the specified model src/Type/App.php57-78

Example configuration value: "User,Role,Product"

Custom Field Workflow:

Sources: src/Type/App.php57-89 src/Type/App.php211-215

Filesystem Configuration

The fs configuration key stores filesystem mount configurations as a JSON array. Each entry defines a storage backend (local, S3, Aliyun OSS, Hostlink) with its connection parameters.

• Key: fs
• Type: JSON array
• Default: Single local filesystem pointing to ./uploads
• Access Method: $app->getFSConfig() returns array
• Structure: Each array element contains:
  • name: Unique identifier for the mount
  • type: Backend type (local, s3, aliyun-oss, hostlink)
  • data: Backend-specific configuration object

Sources: src/App.php695-787 src/App.php134-147

Default Filesystem Configuration

If no fs configuration exists, a default local filesystem is automatically configured:

src/App.php695-715

Configuration Structure by Backend Type

Local Filesystem

Amazon S3 / Compatible

src/App.php749-778

Aliyun OSS

src/App.php745-747

Hostlink Storage

src/App.php780-784

Filesystem Initialization

During Light\App construction, all configured filesystems are loaded into a MountManager instance:

1. getFSConfig() retrieves the JSON array from Config
2. For each config entry, getFS(index) creates the appropriate Flysystem adapter
3. Adapters are added to MountManager with their configured names
4. The MountManager is registered in the DI container src/App.php134-147

Runtime Access

Filesystems can be accessed via:

• GraphQL API: Type\App::getDrive(index) and getDrives() queries src/Type/App.php383-406
• Direct Access: $app->getMountManager() returns the configured MountManager src/App.php149-152
• HTTP Routes: /fs/{protocol}/{path} for authenticated file access src/App.php850-865

For detailed information on file operations and the Node abstraction layer, see File Storage.

Sources: src/App.php134-147 src/App.php695-787 src/Type/App.php363-406

Configuration Management API

Application settings can be queried and modified through the GraphQL API using these queries and mutations:

Queries

• getConfig(): [Config] - Lists all configuration entries (requires config permission) src/Type/App.php338-347
• listConfig(filters, sort): Query - Filtered configuration list (requires config.list permission) src/Type/App.php438-448
• Individual setting queries: getCompany(), isDevMode(), isTwoFactorAuthentication(), etc.

Mutations

Configuration values are modified through AppController:

• updateConfig(name, value) - Updates a single configuration value
• updateConfigs(configs) - Batch updates multiple configuration values

For details on configuration mutations, see AppController.

Sources: src/Type/App.php338-448