Performance: HTML Compression¶

To ensure your application is as fast as possible, PhpSPA includes a powerful, built-in HTML compressor. It automatically minifies your final HTML output by removing whitespace, comments, and other unnecessary characters, which reduces the page size and leads to faster load times. ⚡

Automatic Compression (Default Behavior)¶

PhpSPA automatically initializes the HTML compressor when you create your App instance. The second parameter controls this behavior and is set to true by default.

<?php
use PhpSPA\App;

// Auto-initialization is enabled by default
$app = new App($layout);

// This is the same as:
$app = new App($layout, true);

Disabling Auto-Initialization¶

If you want full manual control over compression, you can disable auto-initialization:

<?php
use PhpSPA\App;

// Disable auto-initialization
$app = new App($layout, false);

// Now you must manually configure compression if you want it
$app->compression(Compressor::LEVEL_AGGRESSIVE, true);

Environment-Based Configuration (Recommended)¶

The easiest way to manage compression is to set the application's environment. PhpSPA will then apply a sensible preset for you.

<?php
use PhpSPA\Compression\Compressor;

$app->compressionEnvironment(Compressor::ENV_DEVELOPMENT);

<?php
use PhpSPA\Compression\Compressor;

$app->compressionEnvironment(Compressor::ENV_PRODUCTION);

Manual Compression Control¶

For more granular control, you can manually set the compression level and enable or disable Gzip.

<?php
use PhpSPA\App;
use PhpSPA\Compression\Compressor;

$app = new App($layout);

// Manually set the highest level of compression and enable Gzip
$app->compression(Compressor::LEVEL_EXTREME, true);

Asset Caching Behavior¶

How Asset Caching Works¶

When you enable compression, PhpSPA generates cached files alongside your component files:

examples/components/
├── Counter.php
└── generated/
    ├── a3f8b2c1d5e9f7a4b2c8d1e6f9a3b7c2.generated.php       # Cached compressed JS
    └── d4e7a1b8c5f2e9d6a3b7c1f4e8a2d5b9.generated.php       # Cached compressed CSS

Smart Cache Invalidation: PhpSPA automatically detects when source files change by using file modification timestamps. When a file changes:

1. The file's modification time updates
2. A new cache hash is generated (based on filename + modification time)
3. The new cache file is created with fresh compressed content
4. Old cache files naturally expire (can be cleaned up periodically)

This means:

• ✅ Production: Excellent performance - compressed content is reused when unchanged
• ✅ Development: Always fresh - file changes automatically generate new cache files
• ✅ No manual tracking: File system timestamps handle everything automatically

Recommended Environment Setup¶

Use environment-based configuration to automatically handle caching:

<?php
use PhpSPA\App;

// Read from environment variable
$app = new App($layout);
$app->compressionEnvironment($_ENV['APP_ENV']);

Then configure your .env file:

APP_ENV=development

APP_ENV=production

Manual Cache Management¶

The cache is automatically managed, but you can manually clear it if needed:

# Delete all generated cache files
find . -name "*.generated.php" -type f -delete

# Or clean up a specific directory
rm -rf /path/to/cache/directory/*.generated.php

Or temporarily disable compression to bypass the cache entirely:

<?php
// Force fresh assets without caching
$app->compression(Compressor::LEVEL_NONE);

IIFE Wrapping for Component Scripts¶

PhpSPA automatically wraps component JavaScript in Immediately Invoked Function Expressions (IIFE) for scope isolation:

• Component JS: Always wrapped in IIFE (()=>{/* your code */})()
• Global JS: Only wrapped when requested via PHPSPA (SPA navigation) to execute in isolation
• External script links: Never wrapped (assumed pre-bundled)

This ensures: - Component scripts don't pollute the global scope - Variables and functions are properly isolated - Global scripts can re-execute during SPA navigation