README

Symfony bundle for caching HTML, JSON, and XML responses as static files. Supports flexible rule-based configuration, auto-cleaning, and CLI tools.

📦 Installation

composer require yurikzt/html-cache-page-bundle

⚙️ Configuration

After installation, create a config file: config/packages/html_cache_page.yaml

html_cache_page:
    enabled: true
    ttl: 3600
    cache_dir: '%kernel.project_dir%/public/cache'

    cacheable_content_types:
        - 'text/html'
        - 'application/json'
        - 'application/xml'
        - 'text/xml'

    cache_rules:
        - pattern: '/blog/*'
          methods: ['GET']
        - pattern: '#^/api/products/\d+$#'
          methods: ['GET']
          parameters:
            format: ['json', 'xml']

    exclude_rules:
        - pattern: '/admin/*'
        - pattern: '/api/auth/*'

    logging:
        enabled: true
        driver: symfony
        logger_service: null

🚀 Usage

Automatic Caching

All HTTP 200 responses that match the cache rules will be saved as files.

Clearing Cache Programmatically

use Yurikzt\HtmlCachePageBundle\Service\CacheCleaner;

class MyController
{
    public function __construct(private CacheCleaner $cacheCleaner) {}

    public function clearCache(): JsonResponse
    {
        $this->cacheCleaner->clearAll();
        $this->cacheCleaner->clearByPattern('/blog/*');
        $this->cacheCleaner->clearByUrl('/blog/my-post');
        $this->cacheCleaner->clearExpired();

        $stats = $this->cacheCleaner->getStats();

        return new JsonResponse(['stats' => $stats]);
    }
}

Console Commands

bin/console html-cache-page:clear --stats
bin/console html-cache-page:clear
bin/console html-cache-page:clear "/blog/*"
bin/console html-cache-page:clear "#^/product/\d+$#"
bin/console html-cache-page:clear --url="/blog/abc"
bin/console html-cache-page:clear --expired

🗂 Cache File Structure

• /blog/post-1 → public/cache/blog/post-1/index.html
• / → public/cache/index.html
• /api/products/1.json → public/cache/api/products/1.json
• Metadata: .meta file alongside each cache file.

{
    "created_at": 1640995200,
    "ttl": 3600,
    "content_type": "text/html",
    "status_code": 200
}

🧠 Rule Options

Pattern Types

• Wildcard: /blog/*
• Regex: #^/product/\d+$#

Query Parameters

parameters:
    q: true
    category: false
    sort: ['name', 'date']
    limit: '10'

📥 HTTP Headers

Bundle adds a header: X-Cache-Status: HIT|MISS

📁 Web Server Configuration

✅ Nginx

location ~* ^/cache/(.*)$ {
    try_files $uri =404;
    access_log off;
    expires 1h;
}

location / {
    try_files $uri $uri/ @cached;
}

location @cached {
    set $cached_file "/cache$uri/index.html";
    if (!-f $document_root$cached_file) {
        set $cached_file "/cache$uri";
    }

    try_files $cached_file @symfony;
}

location @symfony {
    try_files /index.php =404;
}

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param HTTPS off;
}

✅ Apache

<IfModule mod_rewrite.c>
    RewriteEngine On

    RewriteCond %{REQUEST_FILENAME} -f
    RewriteRule ^ - [L]

    RewriteCond %{DOCUMENT_ROOT}/cache%{REQUEST_URI}/index.html -f
    RewriteRule ^ cache%{REQUEST_URI}/index.html [L]

    RewriteCond %{DOCUMENT_ROOT}/cache%{REQUEST_URI} -f
    RewriteRule ^ cache%{REQUEST_URI} [L]

    RewriteRule ^ index.php [L]
</IfModule>

✅ Requirements

• PHP 8.1+
• Symfony 6.0+

📄 License

MIT