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: Never wrapped to prevent duplicate execution and to allow global functions to be reused
• 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 are not wrapped to allow other scripts (global and components) to reuse variables, functions and classes.

⚙️ Native Compressor Configuration¶

🚀 JavaScript Minification with esbuild¶

Starting from v2.0.9, PhpSPA uses the professional esbuild bundler by default for JavaScript minification. Esbuild provides superior minification, bundling, and tree-shaking compared to the built-in C++/PHP minifier.

npm install --global esbuild

Disabling esbuild¶

If you prefer faster compression time with less aggressive minification, or if you encounter issues with esbuild in your environment, you can disable it:

<?php
use PhpSPA\App;

$app = new App($layout);
$app->disableMinificationWithEsbuild();

📂 Custom Compressor Library Path¶

You can specify an absolute path to the native compressor shared library. This is useful if the library is in a non-standard location or you want to use a specific version.

<?php
use PhpSPA\App;

$app = new App($layout);
$app->setCustomCompressorLibraryPath('/path/to/libcompressor.so');

export PHPSPA_COMPRESSOR_LIB="/path/to/libcompressor.so"

<?php
// Or set it in PHP before creating the App
putenv("PHPSPA_COMPRESSOR_LIB=/path/to/libcompressor.so");

$app = new \PhpSPA\App($layout);

🔒 Force Native Compression¶

By default, PhpSPA automatically falls back to PHP compression if the native library is unavailable. Use forceNativeCompression() to enforce native-only mode — the app will throw an exception if the library cannot be loaded.

<?php
use PhpSPA\App;

$app = new App($layout);
$app->forceNativeCompression();

<?php
$app->forceNativeCompression();
$app->setCustomCompressorLibraryPath('/opt/phpspa/libcompressor.so');

<?php
// Let PhpSPA auto-detect and fallback gracefully
// No need to call forceNativeCompression()

🧩 Complete Configuration Example¶

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

$app = new App($layout);

// Force native compression (no PHP fallback)
$app->forceNativeCompression();

// Point to a specific library build
$app->setCustomCompressorLibraryPath(__DIR__ . '/bin/libcompressor.so');

// Use extreme compression with Gzip
$app->compression(Compressor::LEVEL_EXTREME, true);

// esbuild is enabled by default, but you can disable it:
// $app->disableMinificationWithEsbuild();

$app->run();

<?php
$app->forceNativeCompression()
    ->setCustomCompressorLibraryPath('/path/to/lib.so')
    ->compression(Compressor::LEVEL_EXTREME, true)
    ->run();