Controllers

Purpose and Scope

Controllers in the Light framework are PHP classes that expose GraphQL operations (queries and mutations) through annotation-based declaration. They serve as the primary API entry points for client applications, handling authentication flows, configuration management, file operations, and business logic. Controllers use GraphQLite annotations to define schema elements and integrate with the RBAC system for authorization.

For detailed information about specific controllers, see:

• Authentication operations: AuthController
• Configuration and user preferences: AppController
• File system operations: FileSystemController
• User management: User Management Operations
• Audit trail operations: RevisionController

For GraphQL schema generation and type system details, see Schema Generation and Type System. For the root query type, see Root Query Type (Light\Type\App).

---

Controller Architecture Pattern

Controllers in Light are standard PHP classes decorated with GraphQLite annotations. They do not extend a base class but follow a consistent pattern for exposing operations through the GraphQL API.

Controller Class Structure Diagram

Sources: src/Controller/AuthController.php1-636 src/Controller/AppController.php1-150

---

Available Controllers

The Light framework includes several built-in controllers organized by domain:

Controller	File Path	Primary Responsibility	Importance Score
AuthController	src/Controller/AuthController.php	Authentication mutations: login, logout, 2FA, OAuth, password management	69.18
AppController	src/Controller/AppController.php	Configuration updates, user preferences (style, language, menu), session revocation	35.86
FileSystemController	Referenced in architecture	File and folder CRUD operations, uploads, filesystem configuration	40.67
RevisionController	Referenced in architecture	Audit trail queries, revision restoration	Not scored

Sources: Architecture diagrams, src/Controller/AuthController.php1-636 src/Controller/AppController.php1-150

---

Controller Patterns and Conventions

Method Declaration Pattern

Controllers use GraphQLite annotations to declare GraphQL operations:

Example from AuthController:

src/Controller/AuthController.php105-118

Sources: src/Controller/AuthController.php105-118 src/Controller/AppController.php22-27

Authorization Annotations

Controllers enforce authorization through two primary annotations:

Annotation	Purpose	Example	Behavior
@Logged	Requires authentication	#[Logged]	Throws error if user not authenticated
@Right('permission')	Requires specific permission	#[Right('config.update')]	Checks RBAC permission against user roles

Multiple annotations stack to create combined requirements:

src/Controller/AppController.php59-72

Sources: src/Controller/AuthController.php105-118 src/Controller/AppController.php59-72

---

Dependency Injection Patterns

Controllers use GraphQLite's dependency injection through annotations:

Common Dependency Injection Diagram

Example usage patterns:

App Injection - Access core application services:

src/Controller/AuthController.php373-456

User Injection - Access authenticated user:

src/Controller/AuthController.php474-490

Sources: src/Controller/AuthController.php373-456 src/Controller/AuthController.php474-490 src/Controller/AppController.php22-27

---

Controller to GraphQL Operation Mapping

The following diagram shows how controller methods map to GraphQL operations exposed to clients:

Sources: src/Controller/AuthController.php1-636 src/Controller/AppController.php1-150

---

Authentication Flow Pattern

Controllers implement authentication operations following a consistent pattern:

Key implementation details:

1. Account Lockout: Checked via User::isAuthLocked() method src/Controller/AuthController.php403-405
2. Password Verification: Uses PasswordVerify() with legacy hash detection src/Controller/AuthController.php458-465
3. 2FA Validation: Validates TOTP codes when user.secret exists src/Controller/AuthController.php420-428
4. Password Expiration: Checks expiration based on password_dt field src/Controller/AuthController.php446-452
5. Session Creation: Delegates to App::userLogin() for JWT generation src/Controller/AuthController.php454

Sources: src/Controller/AuthController.php373-456 src/Controller/AuthController.php458-465

---

Configuration Management Pattern

AppController provides mutations for managing system configuration:

Configuration Update Flow

Implementation details:

• Single config update: src/Controller/AppController.php59-72
• Batch config update: src/Controller/AppController.php35-57
• Menu configuration: src/Controller/AppController.php74-91

All configuration mutations require:

• @Logged annotation for authentication
• @Right('config.update') or @Right('menu.update') for authorization

Sources: src/Controller/AppController.php35-91

---

User Preference Management

AppController provides mutations for managing per-user preferences:

Mutation	Parameters	Purpose	Authorization
updateMyStyle	name: String!, value: Any!	Updates single style preference	@Logged only
updateMyStyles	value: [KeyValue!]!	Batch updates style preferences	@Logged only
updateMyLanguage	name: String!	Updates user language preference	@Logged only
updateMyMenu	menu: Any!	Updates custom menu configuration	@Logged only

Implementation pattern:

src/Controller/AppController.php105-114

These mutations:

• Require authentication (@Logged) but not specific permissions
• Use @InjectUser to access the authenticated user
• Modify the authenticated user's own data only

Sources: src/Controller/AppController.php105-149

---

OAuth and Social Authentication Pattern

AuthController implements OAuth integration for Google, Microsoft, and Facebook:

OAuth Provider Integration Diagram

Key implementation details:

Google Authentication src/Controller/AuthController.php303-330:

• Requires google/apiclient composer package
• Uses Config::Value("authentication_google_client_id") for client ID
• Stores Google user ID in user.google field

Microsoft Authentication src/Controller/AuthController.php236-267:

• Requires Config::Value("authentication_microsoft_client_id")
• Validates token via Microsoft Graph API
• Stores Microsoft ID in user.microsoft field

Facebook Authentication src/Controller/AuthController.php269-300:

• Requires Config::Value("authentication_facebook_app_id")
• Validates token via Facebook Graph API
• Stores Facebook ID in user.facebook field

Account Linking Pattern: All registration methods clear previous links to prevent duplicate accounts src/Controller/AuthController.php193-196 src/Controller/AuthController.php225-228 src/Controller/AuthController.php138-141

Sources: src/Controller/AuthController.php121-330

---

Session Management

AppController provides session management capabilities:

Session Revocation

src/Controller/AppController.php22-27

This mutation:

• Accepts JWT ID (jti) parameter
• Delegates to User::revokeSession() method
• Allows users to revoke specific active sessions
• Requires authentication but not specific permission

Sources: src/Controller/AppController.php22-27

---

Error Handling Pattern

Controllers use GraphQL errors for exception handling:

src/Controller/AuthController.php399-405

Common error patterns:

• Authentication failures: Generic error messages to prevent user enumeration
• Account lockout: Includes duration from configuration
• 2FA errors: Specific error for setup vs. verification failures
• Password expiration: Dedicated error code "password is expired"
• OAuth errors: Provider-specific error messages

Sources: src/Controller/AuthController.php399-456

---

Custom Controller Development

To create custom controllers, follow this pattern:

1. Create controller class in src/Controller/ namespace
2. Add GraphQL operations using @Query or @Mutation annotations
3. Apply authorization using @Logged and/or @Right annotations
4. Inject dependencies using @Autowire and @InjectUser
5. Return typed values for GraphQL schema generation

The controller will be automatically discovered by GraphQLite's schema factory during application initialization.

For code generation capabilities, see Code Generation. For GraphQL schema details, see Schema Generation and Type System.

Sources: src/Controller/AuthController.php1-636 src/Controller/AppController.php1-150