README

twig-compress-html

A Twig 3 extension wrapping akankov/html-min — exposes an html_min filter and an {% htmlmin %}...{% endhtmlmin %} block tag, with an optional Symfony bundle for auto-registration.

Requirements

PHP 8.3.* || 8.4.* || 8.5.*
twig/twig ^3.0
akankov/html-min ^2.9

Install

composer require akankov/twig-compress-html

Plain Twig usage

use Akankov\HtmlMin\HtmlMin;
use Akankov\TwigCompressHtml\HtmlMinExtension;
use Akankov\TwigCompressHtml\HtmlMinRuntime;
use Twig\Environment;
use Twig\Loader\FilesystemLoader;
use Twig\RuntimeLoader\FactoryRuntimeLoader;

$twig = new Environment(new FilesystemLoader(__DIR__.'/templates'));
$twig->addExtension(new HtmlMinExtension());
$twig->addRuntimeLoader(new FactoryRuntimeLoader([
    HtmlMinRuntime::class => static fn () => new HtmlMinRuntime(new HtmlMin()),
]));

Filter

{{ rawHtml|html_min }}

Block tag

{% htmlmin %}
<html>
  <body>
    {{ content }}
  </body>
</html>
{% endhtmlmin %}

The tag captures rendered output (variables are escaped first by Twig's autoescape, then minified), so it's safe to interpolate user data inside.

Symfony usage

return [
    // ...
    Akankov\TwigCompressHtml\Bundle\AkankovTwigCompressHtmlBundle::class => ['all' => true],
];

Optionally tune HtmlMin via config/packages/akankov_twig_compress_html.yaml:

akankov_twig_compress_html:
    remove_comments: true
    sum_up_whitespace: true
    optimize_attributes: true
    sort_html_attributes: true
    remove_omitted_quotes: false
    minify_inline_css: true
    local_domains: ['example.com']

The filter and tag become available in all templates automatically.

Configuration

Every config key is a snake_case mirror of a property on Akankov\HtmlMin\Config\MinifierOptions; the bundle camel-cases them and builds the options object that backs the shared HtmlMin service, so:

remove_comments: true       # → MinifierOptions::$removeComments
sum_up_whitespace: true     # → MinifierOptions::$sumUpWhitespace
local_domains: ['a.test']   # → MinifierOptions::$localDomains

All of the engine's options are accepted — the 27 boolean toggles plus the list options local_domains, special_html_comments_starting_with, special_html_comments_ending_with, special_script_tags, and template_logic_syntax_in_special_script_tags. Any key you omit falls through to the engine's own default, so the bundle never pins (or drifts from) those defaults. This matches the surface exposed by the Laravel binding's config/htmlmin.php.

Response minification (opt-in)

To minify whole text/html responses — not just {% htmlmin %} blocks — enable the kernel.response listener. It is off by default (the bundle never adds it to the response pipeline on its own), mirroring the Laravel binding's MinifyHtmlResponseMiddleware:

akankov_twig_compress_html:
    minify_responses: true

Sub-requests, streamed responses, and non-text/html responses pass through untouched, so it is safe in front of a mixed JSON / HTML application.

What "pass through" covers, precisely:

Streamed responses (StreamedResponse, BinaryFileResponse) are never buffered or minified — the listener only touches responses whose body it can read as a string.
Partial content (206 responses to range requests) is skipped by the same mechanism in practice — range responses are produced as binary-file responses; minifying a byte range of HTML would corrupt it.
ESI/SSI fragments: the listener runs only on the main request, so edge-side includes assembled by a proxy are minified per-fragment only if your proxy requests them as main requests against this app — in that case each fragment is valid standalone HTML and minifies safely. Fragments rendered as Symfony sub-requests pass through untouched.

Console command

With symfony/console installed, the bundle registers html-min:check — a CI/dev smoke-check that minifies a file in memory and reports the byte savings without writing to disk (mirrors the Laravel binding's Artisan command):

bin/console html-min:check templates/page.html
# [OK] Reduced from 4.2 KB to 3.1 KB (-26.3%)

It exits 0 on success and 1 if the file cannot be read.

Versioning

This package follows Semantic Versioning. From 1.0.0 onward the public surface — the html_min filter, the {% htmlmin %} block tag, the Symfony bundle's config keys, and the opt-in response listener — is stable; breaking changes are reserved for a new major version. The underlying engine is tracked via a caret constraint (akankov/html-min: ^2.9), so it picks up engine minor/patch releases automatically.

Tests

composer install
vendor/bin/phpunit

# line coverage + floor enforcement (needs pcov or xdebug)
make coverage

License

MIT

akankov / twig-compress-html

Maintainers

Package info

Fund package maintenance!

Statistics

Security