Cache Commands

Framefox provides cache management commands to optimize your application’s performance by controlling the service container cache.

Available Commands

cache:clear

Clear all application caches

cache:warmup

Pre-warm the cache for better startup

cache:clear

Clears all cached data including service container cache, command registry, and in-memory caches.

Usage

framefox cache:clear

What Gets Cleared

The command clears multiple cache components:

Service Cache Files - Cached service definitions
Command Cache - Command registry cache
Memory Caches - Resolution and module scan caches
Service Instances - Resets singleton instances (except essential services)
Scan Status - Resets module and source scan flags

Example Output

$ framefox cache:clear

┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Cache Component     ┃ Status  ┃ Details                   ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Service Cache Files │ Cleared │ 3 files removed           │
│ Command Cache       │ Cleared │ Command registry cache    │
│ Memory Caches       │ Cleared │ Resolution: 45, Modules: 12│
│ Service Instances   │ Cleared │ 38 instances removed      │
│ Scan Status         │ Reset   │ Modules: 12, Sources: Yes │
└─────────────────────┴─────────┴───────────────────────────┘

✓ ServiceContainer cache cleared in 0.05 seconds

Next server start will rebuild the service cache automatically

Cache Files Cleared

The command removes these cache files:

var/cache/
├── dev_services.json          # Development service cache
├── services.json               # Production service cache
├── service_definitions.json    # Service definitions
└── command_registry.json       # Command registry

When to Clear Cache

Clear cache when:

After adding new services - Ensure new services are discovered
After modifying decorators - Refresh service metadata
Debugging DI issues - Reset container state
After dependency changes - Clear stale dependencies
Deployment issues - Reset to clean state
Performance degradation - Remove corrupted cache

Essential Services

These services are preserved during cache clear:

Settings - Application configuration
Logger - Logging service
Config - Configuration loader

Other services are reloaded on next request.

cache:warmup

Pre-warms the cache by forcing service discovery, pre-loading essential services, and generating cache files.

Usage

framefox cache:warmup

What Gets Warmed

The command performs these operations:

Service Discovery - Scans and registers all services
Essential Service Loading - Pre-loads critical services
Cache Generation - Creates optimized cache files
Cache Validation - Verifies cache integrity

Example Output

$ framefox cache:warmup

┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Cache Component   ┃ Status     ┃ Details                 ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Service Discovery │ Completed  │ 45 services in 0.12s    │
│ Essential Services│ Pre-loaded │ 15/18 in 0.08s          │
│ Cache Generation  │ Saved      │ 45 services in 0.03s    │
│ Cache Validation  │ Valid      │ Cache valid with 45...  │
└───────────────────┴────────────┴─────────────────────────┘

📊 Container Statistics:

┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓
┃ Metric                ┃ Value ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩
│ Total Definitions     │ 45    │
│ Instantiated Services │ 15    │
│ Cached Resolutions    │ 23    │
│ Total Aliases         │ 8     │
│ Total Tags            │ 15    │
└───────────────────────┴───────┘

✓ ServiceContainer cache warmed up in 0.23 seconds

Essential Services Tagged

Services tagged for pre-loading:

essential - Core framework services
controller - All controllers
security - Authentication/authorization
orm - Database and entity managers
logging - Logging infrastructure

Common Pre-loaded Services

Settings
Logger
Session
EntityManagerRegistry
TokenStorage
SecurityContextHandler
BundleManager

When to Warm Cache

Warm cache:

Before deployment - Optimize production startup
After clearing cache - Rebuild immediately
CI/CD pipeline - Build cache during deployment
Performance testing - Ensure consistent timing
Production startup - Reduce first-request latency

Cache Validation

The warmup validates cache integrity:

Cache Validation Checks

File Exists - Cache file is present
Valid JSON - Cache is properly formatted
Required Keys - Contains version, timestamp, services
Valid Structure - Services array is properly formatted
Service Metadata - Each service has name, class_path, module

Validation Output

Valid Cache:

│ Cache Validation  │ Valid      │ Cache valid with 45 services, version 1.0 │

Invalid Cache:

│ Cache Validation  │ Invalid    │ Missing required keys: services │

❌ Cache Validation Issues:
   • Reason: Missing required keys: services
   • Details: Found keys: ['version', 'timestamp']

⚠️  Cache validation failed - this may affect performance on next startup

Performance Impact

Startup Time Comparison

Scenario	First Request	Subsequent Requests
No Cache	800-1200ms	800-1200ms
Cold Cache	600-800ms	100-200ms
Warm Cache	100-200ms	50-100ms

Cache Benefits

Faster Startup - Pre-discovered services load instantly
Reduced Scanning - No need to scan filesystem
Lower CPU - Less computation on startup
Better UX - Faster first response time
Production Ready - Optimized for production environments

Cache Location

Cache files are stored in:

var/cache/

This directory is:

Created automatically during framefox init
Excluded from git via .gitignore
Cleared on cache:clear
Regenerated on cache:warmup or server start

Best Practices

Development Workflow

# 1. Add new service
vim src/service/my_service.py

# 2. Clear cache
framefox cache:clear

# 3. Warm cache (optional)
framefox cache:warmup

# 4. Run server
framefox run

Deployment Workflow

# In CI/CD pipeline

# 1. Deploy code
git pull origin main

# 2. Install dependencies
pip install -r requirements.txt

# 3. Clear old cache
framefox cache:clear

# 4. Warm new cache
framefox cache:warmup

# 5. Restart application
systemctl restart framefox

Troubleshooting Checklist

Clear cache

Run framefox cache:clear to reset state

Warm cache

Run framefox cache:warmup to rebuild

Check validation

Review validation output for issues

Check logs

Review application logs for errors

Restart server

Restart with fresh cache loaded

Cache Debug Mode

Enable cache debugging in configuration:

# config/debug.yaml
debug:
  cache:
    enabled: true
    log_hits: true
    log_misses: true

This logs cache operations:

[DEBUG] Cache hit: UserRepository
[DEBUG] Cache miss: NewService (discovering...)
[DEBUG] Cache saved: 45 services

Common Issues

Service Not Found After Adding

# Clear and rebuild
framefox cache:clear
framefox cache:warmup
framefox run

Slow Startup in Production

# Ensure cache is warmed
framefox cache:warmup

# Check cache exists
ls -lh var/cache/*.json

Cache Validation Fails

# Remove corrupted cache
rm -rf var/cache/*

# Rebuild
framefox cache:warmup

Environment-Specific Caching

Different cache files for different environments:

Development: dev_services.json (with debug info)
Production: services.json (optimized)

Automatic selection based on APP_ENV:

APP_ENV=dev    # Uses dev_services.json
APP_ENV=prod   # Uses services.json

Commands

Available Commands

cache:clear

cache:warmup

cache:clear

Usage

What Gets Cleared

Example Output

Cache Files Cleared

When to Clear Cache

Essential Services

cache:warmup

Usage

What Gets Warmed

Example Output

Essential Services Tagged

Common Pre-loaded Services

When to Warm Cache

Cache Validation

Validation Output

Performance Impact

Startup Time Comparison

Cache Benefits

Cache Location

Best Practices

Development Workflow

Deployment Workflow

Troubleshooting Checklist

Cache Debug Mode

Common Issues

Service Not Found After Adding

Slow Startup in Production

Cache Validation Fails

Environment-Specific Caching

Next Steps

Debug Commands

Performance

Build docs developers (and LLMs) love

Commands

​Available Commands

cache:clear

cache:warmup

​cache:clear

​Usage

​What Gets Cleared

​Example Output

​Cache Files Cleared

​When to Clear Cache

​Essential Services

​cache:warmup

​Usage

​What Gets Warmed

​Example Output

​Essential Services Tagged

​Common Pre-loaded Services

​When to Warm Cache

​Cache Validation

​Validation Output

​Performance Impact

​Startup Time Comparison

​Cache Benefits

​Cache Location

​Best Practices

​Development Workflow

​Deployment Workflow

​Troubleshooting Checklist

​Cache Debug Mode

​Common Issues

​Service Not Found After Adding

​Slow Startup in Production

​Cache Validation Fails

​Environment-Specific Caching

​Next Steps

Debug Commands

Performance

Build docs developers (and LLMs) love

Available Commands

cache:clear

Usage

What Gets Cleared

Example Output

Cache Files Cleared

When to Clear Cache

Essential Services

cache:warmup

Usage

What Gets Warmed

Example Output

Essential Services Tagged

Common Pre-loaded Services

When to Warm Cache

Cache Validation

Validation Output

Performance Impact

Startup Time Comparison

Cache Benefits

Cache Location

Best Practices

Development Workflow

Deployment Workflow

Troubleshooting Checklist

Cache Debug Mode

Common Issues

Service Not Found After Adding

Slow Startup in Production

Cache Validation Fails

Environment-Specific Caching

Next Steps