Skip to content

STATIC_FILE_MANAGERS.md

Latest commit

 

History

History
463 lines (387 loc) · 13.4 KB

STATIC_FILE_MANAGERS.md

File metadata and controls

463 lines (387 loc) · 13.4 KB

Static File Managers - Complete Guide

📋 Overview

PivotPHP Core provides two complementary static file management solutions, each optimized for different use cases and project scales.

🎯 Manager Comparison

Aspect SimpleStaticFileManager StaticFileManager
Strategy Individual routes per file Dynamic resolution with cache
Best for Small projects (<100 files) Medium/Large projects (100+ files)
Memory Usage Linear per file Optimized with intelligent cache
Performance High for few files Optimized for many files
Features Basic file serving Advanced: ETag, compression, security
Complexity Minimal Full-featured

🚀 SimpleStaticFileManager

Purpose

Direct approach that registers each file as an individual route in the router.

Strategy

  • One file = One route: Each physical file becomes a specific route
  • No wildcards: Direct mapping without pattern matching
  • High performance: Optimal for small file counts
  • Simple caching: File metadata stored in memory

When to Use

  • ✅ Small projects with <100 static files
  • ✅ When you need total control over served files
  • ✅ When routing performance is critical
  • ✅ Simple websites or APIs with minimal assets

Usage Examples

Basic Directory Registration

use PivotPHP\Core\Core\Application;
use PivotPHP\Core\Routing\SimpleStaticFileManager;

$app = new Application();

// Register entire directory - creates individual routes
SimpleStaticFileManager::registerDirectory(
    '/assets',           // Route prefix
    'public/assets',     // Physical path
    $app                 // Application instance
);

// This creates routes like:
// GET /assets/css/style.css → public/assets/css/style.css
// GET /assets/js/app.js     → public/assets/js/app.js
// GET /assets/images/logo.png → public/assets/images/logo.png

Configuration Options

SimpleStaticFileManager::configure([
    'max_file_size' => 5242880,        // 5MB max
    'allowed_extensions' => [
        'css', 'js', 'png', 'jpg', 'svg'
    ],
    'cache_control_max_age' => 3600    // 1 hour cache
]);

Statistics and Monitoring

// Get performance statistics
$stats = SimpleStaticFileManager::getStats();
echo "Registered files: {$stats['registered_files']}\n";
echo "Total hits: {$stats['total_hits']}\n";
echo "Memory usage: " . round($stats['memory_usage_bytes'] / 1024, 2) . " KB\n";

// List all registered file routes
$files = SimpleStaticFileManager::getRegisteredFiles();
foreach ($files as $route) {
    echo "Route: {$route}\n";
}

Technical Details

File Processing Pipeline

  1. Directory Scan: Recursively scans physical directory
  2. Validation: Checks file size, extension, readability
  3. Route Creation: Generates individual route for each file
  4. Handler Registration: Creates optimized handler with file metadata
  5. Memory Storage: Stores file info for quick access

Supported File Types

'js' => 'application/javascript',
'css' => 'text/css',
'html' => 'text/html',
'json' => 'application/json',
'png' => 'image/png',
'jpg' => 'image/jpeg',
'svg' => 'image/svg+xml',
'pdf' => 'application/pdf',
'txt' => 'text/plain',
'woff2' => 'font/woff2'
// ... and more

Response Headers

  • Content-Type: Automatically detected from file extension
  • Content-Length: File size in bytes
  • Cache-Control: Configurable max-age
  • ETag: MD5 hash based on file path, modification time, and size
  • Last-Modified: File modification timestamp

🛡️ StaticFileManager (Advanced)

Purpose

Advanced static file serving with Express.js-like functionality, intelligent caching, and production-ready features.

Strategy

  • Dynamic Resolution: Resolves files on-demand with wildcard patterns
  • Intelligent Cache: Metadata caching with configurable limits
  • Advanced Features: ETag, compression, security, index files
  • Facade Pattern: Uses SimpleStaticFileManager for directory registration

When to Use

  • ✅ Medium/Large projects with 100+ static files
  • ✅ Single Page Applications (SPAs) with asset management
  • ✅ Production environments requiring cache optimization
  • ✅ When you need Express.js static() functionality
  • ✅ Projects requiring advanced security features

Usage Examples

Modern Approach (Recommended)

use PivotPHP\Core\Core\Application;
use PivotPHP\Core\Routing\StaticFileManager;

$app = new Application();

// Register directory (delegates to SimpleStaticFileManager)
StaticFileManager::registerDirectory(
    '/public',
    'public/assets',
    $app,
    [
        'index' => ['index.html', 'index.htm'],
        'dotfiles' => 'ignore',
        'redirect' => true
    ]
);

Legacy Pattern Matching (Backward Compatibility)

// Register with wildcard pattern (legacy method)
$handler = StaticFileManager::register(
    '/static',              // Route prefix
    'public/static',        // Physical directory
    [
        'index' => ['index.html'],
        'dotfiles' => 'ignore',
        'extensions' => false,
        'fallthrough' => true,
        'redirect' => true
    ]
);

// Use handler in route with wildcard
$app->get('/static/*', $handler);

Advanced Configuration

StaticFileManager::configure([
    'enable_cache' => true,
    'max_file_size' => 10485760,       // 10MB
    'max_cache_entries' => 10000,      // Cache limit
    'allowed_extensions' => [
        'js', 'css', 'html', 'png', 'jpg', 'svg', 'woff2'
    ],
    'security_check' => true,          // Path traversal protection
    'send_etag' => true,              // ETag headers
    'send_last_modified' => true,     // Last-Modified headers
    'cache_control_max_age' => 86400  // 24 hours
]);

Advanced Features

File Listing and Discovery

// List all files in registered path
$files = StaticFileManager::listFiles('/public', 'css/', 2);
foreach ($files as $file) {
    echo "Route: {$file['path']}\n";
    echo "Size: {$file['size']} bytes\n";
    echo "Modified: " . date('Y-m-d H:i:s', $file['modified']) . "\n";
    echo "MIME: {$file['mime']}\n\n";
}

Route Mapping and Analysis

// Generate complete route map
$routeMap = StaticFileManager::generateRouteMap();
foreach ($routeMap as $prefix => $info) {
    echo "Prefix: {$prefix}\n";
    echo "Physical Path: {$info['physical_path']}\n";
    echo "File Count: {$info['file_count']}\n";
    
    foreach ($info['files'] as $file) {
        echo "  - {$file['path']} ({$file['extension']})\n";
    }
}

Performance Monitoring

$stats = StaticFileManager::getStats();
echo "Registered paths: {$stats['registered_paths']}\n";
echo "Cached files: {$stats['cached_files']}\n";
echo "Total hits: {$stats['total_hits']}\n";
echo "Cache hits: {$stats['cache_hits']}\n";
echo "Cache misses: {$stats['cache_misses']}\n";
echo "Memory usage: {$stats['memory_usage_mb']} MB\n";

Cache Management

// Clear file cache
StaticFileManager::clearCache();

// Get specific path info
$pathInfo = StaticFileManager::getPathInfo('/public');
if ($pathInfo) {
    echo "Physical path: {$pathInfo['physical_path']}\n";
    echo "Options: " . json_encode($pathInfo['options']) . "\n";
}

🏗️ Architecture and Integration

Application Integration

// The Application class uses StaticFileManager by default
$app = new Application();
$app->staticFiles('/assets', 'public/assets');

// This internally calls:
// StaticFileManager::registerDirectory('/assets', 'public/assets', $app);
// Which then delegates to:
// SimpleStaticFileManager::registerDirectory('/assets', 'public/assets', $app);

Delegation Pattern

// StaticFileManager acts as facade
class StaticFileManager 
{
    public static function registerDirectory($prefix, $path, $app, $options = []) 
    {
        // Delegates to SimpleStaticFileManager for actual registration
        SimpleStaticFileManager::registerDirectory($prefix, $path, $app, $options);
    }
    
    public static function register($prefix, $path, $options = []) 
    {
        // Legacy pattern-based method with advanced features
        return self::createFileHandler($prefix);
    }
}

🚀 Performance Comparison

Benchmark Results (1000 files)

Operation SimpleStaticFileManager StaticFileManager
Registration Time ~50ms ~20ms
Memory Usage ~2MB ~500KB
Request Time ~0.1ms ~0.3ms
Cache Efficiency N/A 95%+

Memory Usage Patterns

// SimpleStaticFileManager: Linear growth
memory_usage = file_count * avg_file_metadata_size

// StaticFileManager: Logarithmic growth with cache
memory_usage = cache_limit * avg_cache_entry_size

🛡️ Security Features

Path Traversal Protection

// Automatic security checks in StaticFileManager
private static function containsPathTraversal(string $path): bool 
{
    return strpos($path, '..') !== false ||
           strpos($path, '\\') !== false ||
           strpos($path, '\0') !== false;
}

File Type Validation

// Both managers validate file extensions
$extension = strtolower(pathinfo($filePath, PATHINFO_EXTENSION));
if (!in_array($extension, self::$config['allowed_extensions'], true)) {
    return null; // File type not allowed
}

Size Limitations

// Configurable file size limits
if ($fileSize > self::$config['max_file_size']) {
    return null; // File too large
}

📊 Best Practices

Choosing the Right Manager

Use SimpleStaticFileManager when:

  • Building small websites or APIs
  • You have <100 static files
  • You need maximum routing performance
  • You want explicit control over served files
  • Memory usage is not a concern

Use StaticFileManager when:

  • Building SPAs or large applications
  • You have 100+ static files
  • You need Express.js-like functionality
  • You want advanced caching and optimization
  • You need production-ready features

Configuration Recommendations

Development Environment

// Focus on developer experience
StaticFileManager::configure([
    'enable_cache' => false,           // Disable for hot reload
    'security_check' => true,          // Always enabled
    'send_etag' => false,             // Disable for development
    'cache_control_max_age' => 0      // No browser cache
]);

Production Environment

// Focus on performance and security
StaticFileManager::configure([
    'enable_cache' => true,
    'max_cache_entries' => 50000,
    'security_check' => true,
    'send_etag' => true,
    'send_last_modified' => true,
    'cache_control_max_age' => 86400  // 24 hours
]);

File Organization

public/
├── assets/
│   ├── css/          # Stylesheets
│   ├── js/           # JavaScript
│   ├── images/       # Images
│   └── fonts/        # Web fonts
├── uploads/          # User uploads (separate handling)
└── static/           # Static pages

🔧 Troubleshooting

Common Issues

Files Not Found

// Check if file is in allowed extensions
$stats = SimpleStaticFileManager::getStats();
if ($stats['registered_files'] === 0) {
    echo "No files registered - check file extensions and permissions\n";
}

High Memory Usage

// Monitor SimpleStaticFileManager memory
$stats = SimpleStaticFileManager::getStats();
if ($stats['memory_usage_bytes'] > 10 * 1024 * 1024) { // 10MB
    echo "Consider switching to StaticFileManager for better memory efficiency\n";
}

Poor Cache Performance

// Check StaticFileManager cache efficiency
$stats = StaticFileManager::getStats();
$hitRate = $stats['cache_hits'] / max(1, $stats['total_hits']);
if ($hitRate < 0.8) {
    echo "Cache hit rate low: " . ($hitRate * 100) . "%\n";
    echo "Consider increasing max_cache_entries\n";
}

Performance Tuning

For SimpleStaticFileManager

// Optimize for fewer, critical files only
SimpleStaticFileManager::configure([
    'allowed_extensions' => ['css', 'js'], // Only essential files
    'max_file_size' => 1048576,            // 1MB limit
]);

For StaticFileManager

// Tune cache for your workload
StaticFileManager::configure([
    'max_cache_entries' => $file_count * 1.5, // 150% of actual files
    'enable_cache' => true,
]);

📚 API Reference

SimpleStaticFileManager Methods

  • registerDirectory(string $prefix, string $path, Application $app, array $options = []): void
  • configure(array $config): void
  • getStats(): array
  • getRegisteredFiles(): array
  • clearCache(): void

StaticFileManager Methods

  • registerDirectory(string $prefix, string $path, Application $app, array $options = []): void
  • register(string $prefix, string $path, array $options = []): callable
  • configure(array $config): void
  • getStats(): array
  • getRegisteredPaths(): array
  • getPathInfo(string $prefix): ?array
  • listFiles(string $prefix, string $subPath = '', int $maxDepth = 3): array
  • generateRouteMap(): array
  • clearCache(): void

🎯 Summary

Both StaticFileManager implementations serve different needs in the PivotPHP ecosystem:

  • SimpleStaticFileManager: Direct, high-performance solution for small projects
  • StaticFileManager: Feature-rich, production-ready solution for larger applications

Choose based on your project size, performance requirements, and feature needs. Both are actively maintained and fully supported.