Deployment and Configuration

This document provides comprehensive guidance for deploying and configuring the Light PHP framework in production environments. It covers environment variable configuration, dependency management through Composer, and performance optimization strategies including caching mechanisms. For information about development tools and CLI commands, see Development Tools. For details about the core application initialization, see Core Application.

---

System Deployment Overview

The Light framework requires proper configuration of environment variables, installation of dependencies, and setup of caching mechanisms to function correctly in production environments.

Sources: composer.json1-66 README.md1-40

---

10.1 Environment Configuration

Required Environment Variables

The Light framework requires specific environment variables to be configured in a .env file at the project root. These variables control database connectivity, security settings, and feature integrations.

Sources: README.md9-27

Database Connection Variables

Variable	Description	Required	Example
DATABASE_HOSTNAME	MySQL server hostname	Yes	localhost or 127.0.0.1
DATABASE_DATABASE	Database name	Yes	light_app
DATABASE_USERNAME	Database user	Yes	root
DATABASE_PASSWORD	Database password	Yes	secret123
DATABASE_PORT	MySQL port	No	3306 (default)
DATABASE_CHARSET	Character encoding	No	utf8mb4 (default)

These variables are consumed by the mathsgod/light-db package to establish database connections. The database configuration is used throughout the framework for model operations and query execution.

Sources: README.md9-17 composer.json32

Security Variables

Variable	Description	Required	Example
JWT_SECRET	Secret key for signing JWT tokens	Yes	Random 64-character string
COOKIE_DOMAIN	Domain for authentication cookies	No	.example.com
COOKIE_SECURE	Enable secure cookie flag (HTTPS only)	No	true in production

The JWT_SECRET is critical for security and must be a cryptographically random string. It is used by firebase/php-jwt package and the Auth\Service class for token generation and validation.

Sources: README.md20-27 composer.json14

OAuth Provider Configuration

The framework supports three OAuth providers for social login functionality. Each provider requires specific credentials obtained from their respective developer consoles.

Variable	Description	Required Package	Provider
GOOGLE_CLIENT_ID	Google OAuth 2.0 client ID	google/apiclient	Google Sign-In
MICROSOFT_CLIENT_ID	Microsoft Azure AD client ID	-	Microsoft Login
FACEBOOK_APP_ID	Facebook application ID	-	Facebook Login
FACEBOOK_APP_SECRET	Facebook application secret	-	Facebook Login

Sources: README.md29-39 composer.json40

System Settings

Variable	Description	Default	Example
TIMEZONE	PHP timezone setting	UTC	Asia/Hong_Kong, America/New_York
MODE	Application mode (dev/prod)	dev	prod for production

The TIMEZONE variable is set during Light\App initialization and affects all date/time operations throughout the application. The MODE variable controls debug output and error reporting levels.

Sources: Based on system architecture analysis

---

10.2 Dependencies and Package Management

Composer Dependency Structure

The Light framework uses Composer for dependency management, with dependencies organized into required core packages and optional feature packages.

Sources: composer.json10-46

Required Packages

The following packages are required for core framework functionality and are automatically installed via composer install:

Package	Version	Purpose
mathsgod/light-server	^1.1	HTTP server implementation, PSR-7/PSR-15 middleware support
mathsgod/light-graphql	^1.2	GraphQL server integration with GraphQLite
mathsgod/light-db	^1.5	Database ORM layer built on Laminas DB
mathsgod/light-rbac	^1.0	Role-based access control system
league/container	^4.2	Dependency injection container (PSR-11)
league/flysystem	^3.15	Filesystem abstraction layer
firebase/php-jwt	^6.11	JWT token generation and validation
symfony/cache	^6.0	Caching implementation (PSR-6/PSR-16)
phpmailer/phpmailer	^6.8	Email sending for password resets and notifications
endroid/qr-code	^4.8	QR code generation for 2FA setup
web-auth/webauthn-lib	^4.9	WebAuthn/FIDO2 biometric authentication
symfony/console	^7.4	CLI tool implementation (bin/light)
symfony/yaml	^6.4	YAML file parsing for configuration
ramsey/uuid	^4.7	UUID generation for filesystem configs

Sources: composer.json10-36

Optional Packages (require-dev)

Optional packages provide additional functionality and must be installed explicitly if needed:

Storage Adapter Packages

These packages enable additional storage backends for the filesystem abstraction layer. The system detects installed adapters at runtime through the Light\App::getTypes() method and MountManager configuration.

Package	Version	Purpose
league/flysystem-aws-s3-v3	^3.24	Amazon S3 cloud storage integration
alphasnow/aliyun-oss-flysystem	^3.4	Alibaba Cloud OSS storage integration
hostlink/hostlink-storage-adapter	^1.0	Hostlink proprietary storage system

Sources: composer.json41-43

OAuth Package

The google/apiclient package enables Google OAuth 2.0 authentication via the AuthController::loginGoogle() method. Without this package, Google Sign-In functionality is unavailable.

Package	Version	Purpose
google/apiclient	^2.15	Google Sign-In OAuth token verification

Sources: composer.json40 README.md29-34

Installation Procedure

Sources: composer.json1-65 README.md1-40

PHP Version Requirement

The framework requires PHP 8.1 or higher as specified in composer.json11 This requirement is driven by modern syntax features used throughout the codebase including attributes, union types, and readonly properties.

Sources: composer.json11

---

10.3 Performance and Caching

The Light framework implements multi-layer caching strategies to optimize performance for GraphQL schema generation, configuration lookups, and database queries.

Caching Architecture

Sources: composer.json20 src/Model/Config.php1-29

GraphQL Schema Caching

The GraphQL schema is generated dynamically from PHP classes using GraphQLite annotations but is cached to avoid expensive reflection operations on every request.

Cache Configuration:

• Cache Pool: Symfony\Component\Cache\Adapter\FilesystemAdapter
• Cache Location: var/cache/graphql/
• Cache Key: Generated from schema factory configuration
• Cache Lifetime: Indefinite (manual invalidation required)
• Usage: GraphQL server initialization in Light\App

Cache Invalidation: During development, clear the cache when modifying GraphQL types or controllers:

Sources: composer.json20

Configuration Value Caching

The Config model provides a static method Config::Value() for retrieving configuration values with default fallbacks. These values are cached at the application service level to minimize database queries.

The Light\App class retrieves and caches configuration values during initialization, storing them in the service container for fast access:

Configuration Key	Usage	Cache Location
mode	Application mode (dev/prod)	Light\App service property
access_token_expire	JWT access token TTL	Auth\Service
refresh_token_expire	JWT refresh token TTL	Auth\Service
fs	Filesystem configurations JSON	MountManager initialization
menus	Custom menu definitions JSON	Menu rendering
features	Feature flags (file_manager, 2fa, revision)	Feature availability checks

Sources: src/Model/Config.php15-27

Production Caching Strategy

For optimal performance in production environments:

1. Enable OPcache: Configure PHP's OPcache to cache compiled bytecode

2. Cache Warm-Up: Pre-generate GraphQL schema cache during deployment

3. Database Query Caching: Enable MySQL query cache for read-heavy workloads

4. Config Preloading: Initialize Light\App during application bootstrap to warm configuration cache

Sources: Based on system architecture and caching patterns

Cache Performance Metrics

Cache Type	Cache Hit Ratio	Performance Impact	Invalidation Frequency
GraphQL Schema	99.9%	50-100ms saved per request	On deployment
Config Values	95%	5-10ms saved per lookup	On admin config change
OPcache Bytecode	100%	20-50ms saved per request	On code deployment

Sources: Performance characteristics based on caching implementation patterns

---

Deployment Checklist

Essential Steps

1. Environment Setup

   • ✓ PHP 8.1+ with required extensions (mbstring, json, pdo_mysql)
   • ✓ MySQL 5.7+ or MariaDB 10.3+
   • ✓ Composer 2.x installed

2. Configuration

   • ✓ Create .env file from template
   • ✓ Set all required database variables
   • ✓ Generate secure random JWT_SECRET
   • ✓ Configure OAuth provider credentials (if using social login)
   • ✓ Set TIMEZONE to application timezone
   • ✓ Set MODE=prod for production

3. Installation

   • ✓ Run composer install --no-dev --optimize-autoloader
   • ✓ Run php bin/light db:install to initialize schema
   • ✓ Install optional storage adapters if needed
   • ✓ Install optional OAuth packages if needed

4. Security

   • ✓ Set restrictive file permissions on .env (0600)
   • ✓ Ensure var/cache/ is writable by web server
   • ✓ Configure COOKIE_SECURE=true for HTTPS
   • ✓ Use strong database passwords

5. Performance

   • ✓ Enable PHP OPcache
   • ✓ Disable OPcache timestamp validation in production
   • ✓ Set appropriate PHP memory limits (256M+)
   • ✓ Configure MySQL query cache if applicable

6. Verification

   • ✓ Test database connectivity
   • ✓ Test admin login (default: admin/admin)
   • ✓ Test GraphQL endpoint
   • ✓ Verify file upload functionality
   • ✓ Test OAuth login flows if configured

Sources: composer.json1-65 README.md1-40 src/Model/Config.php1-29