Core Application (Light\App)

Purpose and Scope

The Light\App class is the central application kernel and primary orchestrator of the Light framework. With an importance score of 149.50 (the highest in the codebase), it serves as the single point of integration for all major subsystems: GraphQL API, authentication, RBAC authorization, file storage, database access, and configuration management.

This document covers the App class implementation, initialization sequence, request lifecycle handling, and integration patterns with other framework components. For details on specific subsystems, see:

• Request lifecycle and middleware: 2.2 Request Lifecycle
• Dependency injection patterns: 2.3 Dependency Injection
• GraphQL API structure: 4 GraphQL API
• Authentication mechanisms: 5 Authentication and Authorization
• Data persistence: 6 Data Layer
• File storage: 7 File Storage

---

Class Structure and Core Responsibilities

The Light\App class implements multiple PSR interfaces to integrate with the HTTP middleware pipeline:

Interface	Purpose
MiddlewareInterface	Processes requests in the middleware stack
RequestHandlerInterface	Handles requests after middleware processing
EventDispatcherAware	Dispatches framework events

Key responsibilities:

1. Container management: Initializes and configures the League Container for dependency injection
2. GraphQL schema: Builds and caches the GraphQL schema using GraphQLite's SchemaFactory
3. Authentication context: Creates Auth\Service instances from incoming requests
4. RBAC enforcement: Loads role hierarchies and permissions from YAML files and database
5. File system routing: Configures Flysystem's MountManager for multi-backend storage
6. Configuration loading: Retrieves runtime settings from the Config model
7. Request routing: Exposes HTTP endpoints for file access and token refresh

Sources: src/App.php38-41 src/App.php59-147

---

Initialization Sequence

Constructor Overview

The Light\App constructor executes a multi-stage initialization sequence that bootstraps all framework subsystems. The process is order-dependent because later stages rely on components initialized in earlier stages.

Sources: src/App.php59-147

Service Registration

The constructor registers all core controllers and models with the dependency injection container. This enables autowiring throughout the application:

Notable registrations:

• Light\App::class → Self-reference for dependency injection
• Controller\FileManagerController::class → Custom factory returning new FileManagerController($this->getDrive(0)) to inject default drive
• Rbac::class → RBAC instance after loading role hierarchies
• MountManager::class → Filesystem mount manager after configuration

Sources: src/App.php74-97 src/App.php365 src/App.php146

Mode Detection and Cache Configuration

The constructor attempts to load the application mode from the Config model:

Mode	Debug Flag	Cache Lifetime	Purpose
dev	true	15 seconds	Development with fast schema rebuilds
prod	false	0 (infinite)	Production with cached schema

If the database is unavailable (e.g., during initial setup), the system defaults to dev mode:

Sources: src/App.php106-119

GraphQL Schema Factory Configuration

The Light\GraphQL\Server instance creates and configures the SchemaFactory:

The namespace registration enables GraphQLite to discover GraphQL types, queries, and mutations by scanning PHP classes in the Light namespace for annotations like @Type, @Query, @Mutation, and @Field.

The type mapper factory bridges Light\Db models to GraphQL types, automatically converting database entities to GraphQL output types using reflection and the Symfony serializer.

Sources: src/App.php121-126

---

Request Processing Pipeline

The App class implements both PSR-15 interfaces to participate in the middleware pipeline and serve as the terminal request handler.

Middleware Processing: process() Method

Key operations in process():

1. OPTIONS handling: Returns empty 200 response for CORS preflight src/App.php502-504
2. Body parsing: Manually decodes JSON request body if not already parsed src/App.php508-511
3. Upload processing: Integrates GraphQL upload middleware for multipart/form-data requests src/App.php513-514
4. Request attributes: Injects App instance into request attributes for downstream access src/App.php516
5. Authentication initialization: Creates Auth\Service from request, extracting and validating JWT tokens src/App.php526-527
6. GraphQL context injection: Registers auth service with schema factory for @Logged and @Right checks src/App.php529-530
7. Container registration: Adds request and auth service to container for controller injection src/App.php533-534

Sources: src/App.php500-537

Request Handling: handle() Method

The terminal request handler executes the GraphQL query and returns a JSON response:

Development vs. Production responses:

Mode	Debug Flags	Output
Development	INCLUDE_DEBUG_MESSAGE | INCLUDE_TRACE	Full stack traces, debug info
Production	None	Error messages only, no traces

Both modes use JSON_UNESCAPED_UNICODE to preserve non-ASCII characters in responses.

Sources: src/App.php154-170

GraphQL Execution: execute() Method

This internal method performs the actual GraphQL query execution:

Parameters passed to GraphQL::executeQuery():

• $schema: Generated from SchemaFactory, cached based on mode
• $query: GraphQL query string from request body
• $rootValue: null (not used in code-first approach)
• $context: New Context instance for request-scoped data
• $variableValues: Variables from request body

Sources: src/App.php567-579

---

RBAC System Integration

The App class orchestrates RBAC initialization by loading role hierarchies and permissions from multiple sources.

RBAC Loading Strategy

Default Role Hierarchy

The system defines a fixed four-level hierarchy:

Each role receives a special permission prefixed with # matching its lowercase name. These special permissions are used internally for role membership checks but are filtered out when listing system permissions.

Sources: src/App.php308-323

Permission Sources

The RBAC system aggregates permissions from four distinct sources:

Source	Type	Purpose	Example
permissions.yml	Static file	Define role-to-permission mappings	Administrators: [user:write, role:write]
Role table	Database	Custom role hierarchies	Parent-child role relationships
Permission table	Database	Dynamic permission grants	Grant fs.file:write to specific user
UserRole table	Database	User-to-role assignments	Assign user to "Administrators"

Database loading logic:

Sources: src/App.php324-363

Permission Discovery via Reflection

The getPermissions() method scans the codebase for @Right annotations to build a comprehensive list of all defined permissions:

This discovery mechanism enables the system to enumerate all permissions without manual configuration, supporting permission management UIs and validation.

Sources: src/App.php392-472

---

File System Management

The App class configures Flysystem's MountManager to provide unified access to multiple storage backends.

Filesystem Configuration Structure

File system configurations are stored in the Config model under the key fs as JSON:

MountManager Initialization

Default configuration behavior:

If no Config.fs entry exists, the system creates a single local filesystem:

• Location: getcwd() . "/uploads"
• Public URL: /api/uploads/
• Name: local

Sources: src/App.php134-146 src/App.php695-715

Filesystem Adapter Creation: getFS() Method

The getFS() method instantiates Flysystem adapters based on configuration type:

Type	Adapter	Required Data Fields
local	LocalFilesystemAdapter	location, optional public_url
aliyun-oss	AliyunFactory	Full OSS configuration
s3	AwsS3V3Adapter	region, endpoint, bucket, accessKey, secretKey, prefix, visibility
hostlink	HL\Storage\Adapter	token, endpoint

Local filesystem configuration:

Sources: src/App.php717-787

Drive Abstraction

The getDrive() method wraps a filesystem configuration in a Light\Drive\Drive object:

The Drive class provides a high-level interface for:

• Accessing filesystem metadata (name, type, index)
• Retrieving the underlying Flysystem instance
• Accessing raw configuration data

Sources: src/App.php834-839

---

Configuration and Feature Flags

The App class provides numerous methods to query runtime configuration and feature flags.

Configuration Methods

Token Expiration Configuration

The App class centralizes JWT token lifetime management:

Method	Config Key	Default	Unit	Purpose
getAccessTokenExpire()	access_token_expire	900	Seconds	Short-lived API access token
getRefreshTokenExpire()	refresh_token_expire	604800	Seconds	Long-lived token refresh

Cookie configuration for access tokens:

The system supports partitioned cookies for third-party contexts when both HTTPS is enabled and COOKIE_PARTITIONED=true.

Sources: src/App.php602-629 src/App.php631-685

Menu System

The App class loads menus from two sources:

Menu structure:

Each menu item can contain:

• label: Display text
• to: Route path
• icon: Icon name (e.g., sym_o_folder)
• permission: Required permission(s) for visibility
• children: Nested menu items

The getFlatMenus() method flattens the hierarchical structure for permission extraction and validation.

Sources: src/App.php174-191 src/App.php194-221

Mailer Configuration

The getMailer() method constructs a PHPMailer instance with configuration from the Config model:

Driver	Configuration Required
sendmail	None (uses system sendmail)
qmail	None (uses system qmail)
gmail	SMTP with OAuth2 (mail_host, mail_username, OAuth token)
smtp	mail_host, mail_username, mail_password, mail_port, mail_encryption

Additional settings:

• mail_from / mail_from_name: Sender address
• mail_reply_to / mail_reply_to_name: Reply-to address

Sources: src/App.php233-285

---

HTTP Server and Custom Routes

Server Lifecycle: run() Method

The run() method starts the HTTP server and registers custom routes for file access and token refresh:

File Access Routes

Protocol-based file access: GET /fs/{protocol}/{path:.*}

This route enables location string-based file retrieval using the MountManager:

Example usage: GET /api/fs/local/documents/report.pdf retrieves local://documents/report.pdf

Index-based drive access: GET /drive/{index}/{path:.*}

This route accesses files through the drive abstraction:

Both routes require authentication via Auth\Service.

Sources: src/App.php850-875

Token Refresh Endpoint

Route: POST /refresh_token

This endpoint exchanges a refresh token for a new access token:

Token payload transformation:

Security considerations:

1. The refresh token jti is preserved in the access token, enabling session tracking in UserLog
2. Refresh tokens are path-scoped to /refresh_token during creation
3. On error, the access token cookie is immediately cleared
4. Invalid tokens return 401 with error message

Sources: src/App.php877-920

---

User Login Flow

The userLogin() method orchestrates the complete login sequence:

UserLog entry structure:

Field	Value	Purpose
user_id	User's ID	Link to user
login_dt	Current timestamp	Track login time
result	"SUCCESS"	Login outcome
ip	$_SERVER["REMOTE_ADDR"]	Source IP
user_agent	$_SERVER["HTTP_USER_AGENT"]	Browser info
jti	UUID	Link to JWT tokens

The jti field enables:

• Session tracking: Query all active sessions for a user
• Session revocation: Invalidate specific sessions by blacklisting the jti
• Token refresh: Maintain session continuity across token rotations

Sources: src/App.php631-685

---

WebAuthn Integration

The App class provides helper methods for WebAuthn/FIDO2 configuration:

RP Entity Creation

RP ID determination:

1. Check $_ENV["RP_ID"] for explicit configuration
2. Fall back to $_SERVER["SERVER_NAME"]
3. Replace 0.0.0.0 with localhost for local development

The RP entity is used during WebAuthn credential registration and authentication ceremonies.

Sources: src/App.php804-832

---

Utility Methods

IP Geolocation

The getIpLocation() method queries the ip-api.com service with caching:

Cache key: geoip_{ip}
TTL: 60 seconds

This method is typically used for login logging and security analysis.

Sources: src/App.php924-939

Container and Component Access

The App class exposes getter methods for all major components:

Method	Return Type	Purpose
getContainer()	ContainerInterface	DI container access
getSchemaFactory()	SchemaFactory	GraphQL schema factory
getAuthService()	Auth\Service	Current request's auth context
getRbac()	Rbac	RBAC permission system
getCache()	CacheInterface	PSR cache implementation
getMountManager()	MountManager	Filesystem mount manager
getDatabase()	Adapter	Database connection
getMailer()	Mailer	Configured PHPMailer

These methods enable controllers and services to access framework components without direct container interaction.

Sources: src/App.php223-493

---

Summary

The Light\App class serves as the central orchestration hub for the Light framework, coordinating:

1. Dependency injection via League Container
2. GraphQL schema generation using GraphQLite with automatic type mapping
3. RBAC permission enforcement from YAML files, database, and code annotations
4. Multi-backend file storage through Flysystem's MountManager
5. JWT authentication with dual-token (access/refresh) architecture
6. Configuration management combining environment variables, database settings, and YAML files
7. HTTP routing for file access and token refresh

The initialization sequence is carefully ordered to handle dependencies, with graceful degradation when the database is unavailable (defaulting to dev mode). All major subsystems register themselves with the container during construction, enabling autowiring throughout controllers and services.

For implementation details on specific subsystems, refer to the related wiki pages listed at the beginning of this document.