Performance and Caching

This document covers the caching mechanisms and performance optimization strategies in the Light framework. It details how the framework uses cache to improve GraphQL schema generation, reduce database queries, and optimize API response times. For database query optimization and indexing, see Database Schema (db.json). For GraphQL schema generation specifics, see Schema Generation.

---

Cache Architecture Overview

The Light framework implements a multi-layer caching strategy using Symfony Cache and PSR-16 Simple Cache interfaces. Cache behavior is controlled by the application mode (development vs production) and affects GraphQL schema generation, query execution, and application-level data storage.

Sources: src/App.php59-147 src/App.php228-231

---

Cache Configuration System

The cache system is initialized during application bootstrap with configuration determined by the application mode stored in the database. The mode affects cache lifetimes and debug output verbosity.

Mode Detection and Cache Initialization

Sources: src/App.php104-124

Configuration Parameters

Parameter	Development Mode	Production Mode	Purpose
defaultLifetime	15 seconds	0 seconds	GraphQL schema cache TTL
debug	true	false	Debug trace inclusion in responses
mode	"dev"	"prod"	Overall application mode

The defaultLifetime parameter controls how long GraphQL type definitions and resolvers are cached. In development, a short 15-second cache allows rapid iteration while still providing some performance benefit. In production, a value of 0 typically means caching is handled differently or uses a more sophisticated strategy.

Sources: src/App.php104-119

---

Cache Implementation

The framework uses Symfony Cache component which provides PSR-6 and PSR-16 compatible caching with support for multiple backends (filesystem, Redis, Memcached, APCu, etc.).

Cache Interface Access

The cache is accessible throughout the application via App::getCache() method, returning a PSR-16 CacheInterface implementation. This allows any component with access to the App instance to leverage caching.

Sources: src/App.php228-231 composer.lock3804-3903

Cache Storage Backend

The Symfony Cache component is configured in the GraphQL Server initialization. By default, it uses the filesystem cache adapter, but can be configured for:

• Filesystem Cache: Default, stores in system temp directory
• APCu: In-memory cache for single-server deployments
• Redis: Distributed caching for multi-server setups
• Memcached: Alternative distributed cache
• Array Cache: In-memory, request-lifetime only (testing)

Sources: composer.lock3818-3825

---

GraphQL Schema Caching

The most significant performance optimization is GraphQL schema caching, which prevents re-parsing and re-validating type definitions on every request.

Schema Factory and Cache Integration

The SchemaFactory is created with cache integration and automatically stores compiled schemas. In development mode (15-second cache), schema changes are picked up quickly. In production mode, schemas are cached more aggressively or potentially indefinitely until manual invalidation.

Sources: src/App.php121-127

Schema Factory Configuration

The factory is configured once during application initialization with namespaces to scan, custom type mappers, and authentication/authorization services. These configurations affect what gets cached.

Sources: src/App.php124-127 src/App.php490-493 src/App.php529-531

---

Runtime Application Caching

Beyond schema caching, the application uses cache for runtime data storage to reduce external API calls and expensive computations.

IP Geolocation Caching Example

The getIpLocation() method demonstrates application-level caching with a 60-second TTL:

This pattern can be applied to any expensive operation:

1. Generate cache key based on input parameters
2. Check cache for existing data
3. If miss, perform expensive operation
4. Store result in cache with appropriate TTL
5. Return data

Sources: src/App.php928-943

Cache Key Naming Convention

Based on the codebase example:

• Prefix by category: geoip_ for IP location data
• Include unique identifier: The IP address in the geolocation example
• Use simple strings: Cache keys should be filesystem-safe

Sources: src/App.php931 src/App.php940

---

Performance Optimization Strategies

Development vs Production Configuration

Sources: src/App.php107-119 src/App.php160-164

Debug Output Impact

The isDevMode() check controls debug trace inclusion in GraphQL responses:

Production responses exclude debug information, reducing payload size and preventing sensitive information leakage.

Sources: src/App.php154-170 src/App.php581-584

Cache Access Pattern

Components needing cache access follow this pattern:

1. During Request Processing: Access via Auth\Service or dependency injection
2. In Controllers: Request App instance from DI container
3. Direct Access: Call $app->getCache() method

Sources: src/App.php228-231 src/App.php74

---

Cache Lifetime Management

The framework uses different TTL strategies for different types of cached data:

Data Type	TTL	Justification
GraphQL Schema (dev)	15 seconds	Allows rapid iteration without restart
GraphQL Schema (prod)	0 or infinite	Stable schema, invalidate on deployment
IP Geolocation	60 seconds	External API, infrequent changes
User-defined	Variable	Application-specific requirements

Manual Cache Invalidation

While not explicitly shown in the provided code, cache can be cleared programmatically:

For GraphQL schema cache, changing the mode or restarting the application forces schema regeneration.

Sources: src/App.php228-231

---

Environment-Specific Configuration

The cache behavior is controlled by the mode configuration stored in the Config model:

To change the mode, update the Config record:

The change takes effect on the next application initialization (typically next request or after server restart).

Sources: src/App.php107-119

---

Performance Monitoring Considerations

While the framework doesn't include built-in performance monitoring, these are key metrics to track:

1. Cache Hit Rate: Percentage of cache lookups that succeed
2. Schema Build Time: Time to generate GraphQL schema on cache miss
3. Response Time: API response latency in dev vs prod modes
4. Cache Memory Usage: Memory consumed by cached data
5. Cache Eviction Rate: How often cached items expire or are evicted

The debug mode responses (development) include timing and trace information that can be used for profiling:

Sources: src/App.php160-164

---

Summary

The Light framework's caching strategy focuses on GraphQL schema optimization while providing flexible runtime caching for application data. The mode-based configuration allows developers to balance between development convenience (fast cache expiry, debug output) and production performance (aggressive caching, minimal payload size). The PSR-16 cache interface enables easy integration with various caching backends without changing application code.

For extending caching to custom models and queries, see Base Model Class. For configuring production environments, see Environment Configuration.