ctw/ctw-middleware-htmlminifier

This PSR-15 middleware formats, fixes and beautifies the HTML in the Response body using a variety of adapters.

4.0.4 2025-11-25 09:10 UTC

Requires

• php: ^8.3
• ext-tidy: *
• ctw/ctw-middleware: ^4.0
• psr/container: ^1.0 || ^2.0

Requires (Dev)

• ctw/ctw-qa: ^5.0
• phpunit/phpunit: ^12.0
• symfony/var-dumper: ^7.0

BSD-3-Clause

README

PSR-15 middleware that minifies HTML responses using pluggable adapters, reducing bandwidth and improving page load times.

Introduction

Why This Library Exists

HTML generated by template engines often contains excessive whitespace, comments, and formatting that increases page size without benefiting end users. Minifying HTML at the response level provides several advantages:

• Reduced bandwidth: Smaller responses transfer faster, especially on mobile networks
• Lower hosting costs: Less data transferred means reduced bandwidth bills
• Improved performance: Smaller payloads parse faster in browsers
• Production optimization: Keep source templates readable while serving optimized output

This middleware intercepts HTML responses and minifies them transparently, with multiple adapter options to balance speed versus compression ratio.

Problems This Library Solves

1. Bloated HTML: Template engines produce readable but unnecessarily large output
2. Manual optimization: Without automation, developers must manually minify HTML
3. Inconsistent minification: Different approaches across a codebase lead to varying output quality
4. Build complexity: Template-level minification complicates the build process
5. Debugging difficulty: Aggressive minification can break HTML; adapters provide different safety levels

Where to Use This Library

• Production environments: Reduce HTML size for faster page loads
• High-traffic sites: Minimize bandwidth costs at scale
• Mobile-first applications: Optimize for slower network connections
• Content-heavy pages: Blog posts, documentation, and marketing pages benefit most
• API responses: HTML fragments returned by AJAX endpoints

Design Goals

1. Pluggable adapters: Choose the right minification strategy for your needs
2. Safe defaults: Conservative minification that won't break valid HTML
3. Transparent operation: Works automatically on HTML responses only
4. Statistics tracking: Appends an HTML comment showing compression ratio
5. Zero template changes: Minifies at response level, not template level

Requirements

• PHP 8.3 or higher
• ext-tidy
• ctw/ctw-middleware ^4.0

Installation

Install by adding the package as a Composer requirement:

composer require ctw/ctw-middleware-htmlminifier

Usage Examples

Basic Pipeline Registration (Mezzio)

use Ctw\Middleware\HtmlMinifierMiddleware\HtmlMinifierMiddleware;

// In config/pipeline.php or similar
$app->pipe(HtmlMinifierMiddleware::class);

ConfigProvider Registration

// config/config.php
return [
    // ...
    \Ctw\Middleware\HtmlMinifierMiddleware\ConfigProvider::class,
];

Available Adapters

Adapter	Description	Speed	Compression
SimpleAdapter	Regex-based whitespace removal	Fast	Moderate
TidyAdapter	Uses PHP's Tidy extension for safe minification	Medium	Good
WyriHaximusAdapter	Full-featured HTML compressor (requires additional package)	Slower	Best

Using SimpleAdapter

The SimpleAdapter uses regular expressions for fast, lightweight minification:

use Ctw\Middleware\HtmlMinifierMiddleware\Adapter\SimpleAdapter\SimpleAdapter;

Performs:

• Removes multi-line whitespace
• Removes HTML comments
• Collapses multiple spaces
• Strips whitespace around tags

Using TidyAdapter

The TidyAdapter leverages PHP's Tidy extension for standards-compliant minification:

use Ctw\Middleware\HtmlMinifierMiddleware\Adapter\TidyAdapter\TidyAdapter;

Features:

• Fixes malformed HTML
• Validates HTML5 doctype
• Configurable output formatting
• Safe for production use

Using WyriHaximusAdapter

For maximum compression, install the optional dependency:

composer require wyrihaximus/html-compress

use Ctw\Middleware\HtmlMinifierMiddleware\Adapter\WyriHaximusAdapter\WyriHaximusAdapter;

Output Statistics

The middleware appends an HTML comment showing compression statistics:

<!-- html: in 15420 b | out 12336 b | diff 20.0000 % -->

Field	Description
in	Original HTML size in bytes
out	Minified HTML size in bytes
diff	Percentage reduction achieved

Selective Processing

The middleware automatically:

• Only processes responses with Content-Type: text/html or application/xhtml
• Passes through empty responses unchanged
• Skips non-HTML responses (JSON, images, etc.)