AppController

Purpose and Scope

The AppController class provides GraphQL mutations and queries for managing application-wide configuration and user-specific preferences. This controller handles system settings stored in the Config model, custom menu definitions, user style preferences, language settings, and session revocation operations.

For authentication-related operations (login, logout, password management), see AuthController. For file system operations, see FileSystemController. For general system queries (permissions, menus from YAML), see Root Query Type.

Sources: src/Controller/AppController.php1-151

---

GraphQL Operations Overview

The AppController exposes the following GraphQL operations:

Operation	Type	Authentication	Authorization	Purpose
getApp	Query	None	None	Returns the root App type
updateAppConfig	Mutation	@Logged	config.update	Updates a single configuration value
updateAppConfigs	Mutation	@Logged	config.update	Batch updates multiple configurations
updateAppMenus	Mutation	@Logged	menu.update	Updates custom menu definitions
getAppMenus	Query	@Logged	None	Returns custom menus (deprecated)
updateMyStyle	Mutation	@Logged	None	Updates a single user style preference
updateMyStyles	Mutation	@Logged	None	Batch updates user style preferences
updateMyLanguage	Mutation	@Logged	None	Sets user's language preference
updateMyMenu	Mutation	@Logged	None	Updates user's menu customization
revokeSession	Mutation	@Logged	None	Revokes a specific user session by JWT ID

Sources: src/Controller/AppController.php22-150

---

Operation Flow Diagram

Sources: src/Controller/AppController.php1-151

---

System Configuration Management

Configuration Update Operations

The controller provides two methods for updating system configuration stored in the Config model:

Single Configuration Update (updateAppConfig)

• Updates one configuration key-value pair
• Creates the config entry if it doesn't exist
• Requires config.update permission
• Implementation: src/Controller/AppController.php62-72

Batch Configuration Update (updateAppConfigs)

• Updates multiple configurations in a single operation
• Accepts an array of {name, value} objects
• Clears the entire application cache after updates
• Requires config.update permission
• Implementation: src/Controller/AppController.php41-57

Configuration Storage Pattern

Key Implementation Details:

1. Upsert Pattern: The controller checks if a configuration exists using Config::Get(["name" => $name]). If not found, it creates a new entry with Config::Create(["name" => $name]) src/Controller/AppController.php44-48 src/Controller/AppController.php64-68

2. Cache Invalidation: After batch configuration updates, the controller calls $app->getCache()->clear() to ensure all cached data (including GraphQL schema cache) reflects the new configuration src/Controller/AppController.php54

3. Authorization: Both methods require the config.update permission enforced via @Right('config.update') annotation src/Controller/AppController.php37 src/Controller/AppController.php61

Sources: src/Controller/AppController.php35-72

---

Menu Configuration Management

The controller manages custom menu definitions stored in the Config model under the key "menus".

Update Custom Menus

Operation: updateAppMenus

• Stores menu definitions as JSON in the Config table
• Requires menu.update permission
• Creates the config entry if it doesn't exist
• Implementation: src/Controller/AppController.php80-91

Retrieve Custom Menus (Deprecated)

Operation: getAppMenus

• Marked as @deprecated in favor of querying app { customMenus }
• Delegates to LightApp::getCustomMenus() method
• Implementation: src/Controller/AppController.php99-102

Storage Format:

• Menus are stored as a JSON string in Config.value
• The key is always "menus"
• Encoding occurs at line 87: $menus->value = json_encode($data)

Sources: src/Controller/AppController.php74-102

---

User Preference Management

The controller provides mutations for managing user-specific preferences. These operations require authentication (@Logged) but no additional permissions, allowing any authenticated user to customize their own experience.

Style Preferences

User style preferences support arbitrary key-value pairs for frontend customization (themes, layouts, UI settings).

Single Style Update (updateMyStyle)

• Parameters: name (string), value (mixed type)
• Delegates to User::updateStyle($name, $value)
• Implementation: src/Controller/AppController.php110-114

Batch Style Update (updateMyStyles)

• Parameters: value (associative array)
• Iterates through array and updates each style preference
• Implementation: src/Controller/AppController.php120-126

Language Preference

Operation: updateMyLanguage

• Sets the user's preferred language code
• Updates User.language field directly
• Implementation: src/Controller/AppController.php132-137

Menu Customization

Operation: updateMyMenu

• Stores user's menu customization (collapsed state, pinned items, etc.)
• Updates User.menu field with mixed data
• Implementation: src/Controller/AppController.php144-149

User Preference Flow

Sources: src/Controller/AppController.php105-149

---

Session Management

Session Revocation

Operation: revokeSession

• Revokes a specific user session by its JWT ID (jti)
• Only allows users to revoke their own sessions
• Delegates to User::revokeSession($jti) method
• Implementation: src/Controller/AppController.php24-27

Key Features:

1. User Context: Uses #[InjectUser] to ensure only the authenticated user can revoke their own sessions
2. JWT Identification: Each session is identified by its JWT ID (jti claim)
3. Immediate Effect: Revocation occurs immediately via cache-based token blacklisting
4. Audit Trail: The revocation is also recorded in the UserLog table

For details on the revocation mechanism, see JWT Token System and User Model and Sessions.

Sources: src/Controller/AppController.php22-27

---

Authorization and Security

Permission Model

The controller implements a three-tier authorization model:

Permission Level	Operations	Authorization
None	getApp	Public access
Authenticated	User preferences, session revocation	@Logged annotation
System Administrator	Configuration updates, menu management	@Logged + @Right

Permission Requirements

System Configuration Rights:

• config.update: Required for updateAppConfig and updateAppConfigs src/Controller/AppController.php37 src/Controller/AppController.php61
• Allows modification of system-wide settings affecting all users

Menu Management Rights:

• menu.update: Required for updateAppMenus src/Controller/AppController.php76
• Allows modification of custom menu structures

User Preferences:

• No additional permissions beyond authentication
• Users can modify their own style, language, and menu preferences
• Enforced through #[InjectUser] which binds operations to the authenticated user

Security Annotations

Sources: src/Controller/AppController.php23-24 src/Controller/AppController.php36-37 src/Controller/AppController.php60-61 src/Controller/AppController.php75-76 src/Controller/AppController.php106 src/Controller/AppController.php116 src/Controller/AppController.php131 src/Controller/AppController.php140

---

Integration with Other Systems

Dependency Injection

The controller uses GraphQLite's dependency injection annotations to access system components:

#[Autowire] LightApp $app

• Injects the core Light\App instance
• Used to access cache ($app->getCache()) src/Controller/AppController.php54
• Used to retrieve custom menus ($app->getCustomMenus()) src/Controller/AppController.php101
• Usage: src/Controller/AppController.php24 src/Controller/AppController.php41 src/Controller/AppController.php99

#[InjectUser] User $user

• Injects the authenticated User model instance
• Provides access to user-specific methods and properties
• Usage: src/Controller/AppController.php24 src/Controller/AppController.php110 src/Controller/AppController.php120 src/Controller/AppController.php132 src/Controller/AppController.php144

Model Interactions

Config Model Integration:

• All configuration operations use the Config model's static methods: Get() and Create() src/Controller/AppController.php44 src/Controller/AppController.php64 src/Controller/AppController.php82
• Configuration is stored as key-value pairs in the database
• Menu configurations are JSON-encoded before storage src/Controller/AppController.php87

User Model Integration:

• User preferences are stored directly in User model fields: language, menu
• Style preferences use the User::updateStyle() method src/Controller/AppController.php112
• Session revocation delegates to User::revokeSession() src/Controller/AppController.php26

Cache Integration:

• Cache clearing occurs after batch configuration updates to ensure consistency src/Controller/AppController.php54
• Invalidates GraphQL schema cache, configuration cache, and other cached data

Sources: src/Controller/AppController.php1-151

---

Related Documentation

For comprehensive understanding of the configuration and preference management system:

• Config Model and Settings: Details on the Config model structure and usage patterns
• Application Settings: Common configuration keys and their purposes
• Menu System: Menu structure, YAML definitions, and permission filtering
• User Model and Sessions: User model fields, session tracking, and revocation mechanics
• RBAC System: Role-based permission checking and enforcement
• Root Query Type: System-level queries for permissions and menus

Sources: src/Controller/AppController.php1-151