README

A lightweight, generic HTML fragment caching package for Laravel. Cache any rendered HTML by identifier (customer/org/user/etc.) with support for all Laravel cache drivers, Blade directives, and simple invalidation.

Features

• 🚀 Laravel 10/11/12 compatible
• 💾 Universal cache support - Works with Redis, Memcached, Database, File, Array, DynamoDB, and Octane
• 🎯 Identifier-based caching - Cache by customer, organization, user, or any identifier
• 🏷️ Blade directive - Simple @fragmentCache directive for quick caching
• ⚡ Performance optimized - Skip database queries and Blade rendering on cache hits
• 🔧 Configurable cache store - Use any cache store from your Laravel configuration
• 🎨 Clean API - Simple facade and trait-based usage
• 🛠️ Artisan commands - Interactive commands for cache management

Installation

You can install the package via Composer:

composer require iperamuna/laravel-html-fragment-cache

The package will automatically register its service provider and facade.

Publish Configuration (Optional)

php artisan vendor:publish --provider="Iperamuna\HtmlFragmentCache\HtmlFragmentCacheServiceProvider" --tag=config

This will publish config/fragment-cache.php where you can customize the default settings.

Configuration

The package uses Laravel's cache system and supports all cache drivers. You can configure which cache store to use and enable/disable caching globally:

# In your .env file
FRAGMENT_CACHE_ENABLED=true
FRAGMENT_CACHE_STORE=redis
# or
FRAGMENT_CACHE_STORE=memcached
# or
FRAGMENT_CACHE_STORE=database
# etc.

Available Configuration Options

// config/fragment-cache.php
return [
    // Enable or disable fragment caching globally
    'enabled' => env('FRAGMENT_CACHE_ENABLED', true),
    
    // Cache store to use for fragment caching (must be one from config/cache.php stores)
    'cache_store' => env('FRAGMENT_CACHE_STORE', 'default'),
    
    // Default TTL for cached fragments
    'default_ttl' => env('FRAGMENT_CACHE_TTL', '6 hours'),
    
    // Default key parts
    'variant' => env('FRAGMENT_CACHE_VARIANT', 'html_fragment'),
    'version' => env('FRAGMENT_CACHE_VERSION', 'v1'),
    
    // Identifier resolution
    'identifier' => [
        'prefix' => env('FRAGMENT_CACHE_ID_PREFIX', ''),
        'sources' => [
            ['type' => 'property', 'path' => 'customer.id', 'label' => 'customer'],
            ['type' => 'property', 'path' => 'organization.id', 'label' => 'org'],
            ['type' => 'route', 'name' => 'customer', 'label' => 'customer'],
            ['type' => 'route', 'name' => 'organization', 'label' => 'org'],
        ],
        'resolver' => Iperamuna\HtmlFragmentCache\Resolvers\DefaultIdentifierResolver::class,
    ],
];

Enabling/Disabling Caching

You can globally enable or disable fragment caching using the enabled configuration option:

# Disable fragment caching (useful for development or debugging)
FRAGMENT_CACHE_ENABLED=false

# Enable fragment caching (default)
FRAGMENT_CACHE_ENABLED=true

When caching is disabled:

• All rememberHtml() calls will execute the builder function directly without caching
• forget() calls will do nothing
• Blade directives will render content directly without caching
• This is useful for development, debugging, or when you want to temporarily disable caching

Usage

Basic Usage with Facade

use FragmentCache;

public function show(Customer $customer)
{
    $html = FragmentCache::rememberHtml(
        identifier: "customer:{$customer->id}",
        builder: function () use ($customer) {
            $products = $customer->products()
                ->select('id','name','image_url','category')
                ->orderBy('name')
                ->get();

            return view('components.dashboard.products-widget', compact('products'))->render();
        },
        ttl: '6 hours',
        variant: 'products_widget_html',
        version: 'v1'
    );

    return view('dashboard.index', ['productsWidgetHtml' => $html]);
}

Blade Directive

The package provides a convenient Blade directive for quick caching:

@fragmentCache('customer:'.$customer->id)
    {{-- expensive HTML here --}}
    <div class="products-widget">
        @foreach($customer->products as $product)
            <div class="product-item">{{ $product->name }}</div>
        @endforeach
    </div>
@endFragmentCache

You can also pass an array as identifier to include additional context:

@fragmentCache([$customer->id, app()->getLocale(), 'v2'])
    {{-- HTML with locale and version context --}}
@endFragmentCache

Using the Trait

For more complex scenarios, use the UsesHtmlFragmentCache trait:

use Iperamuna\HtmlFragmentCache\Concerns\UsesHtmlFragmentCache;

class ProductController extends Controller
{
    use UsesHtmlFragmentCache;

    public function show(Customer $customer)
    {
        $html = $this->cacheFragmentHtml(
            identifier: "customer:{$customer->id}",
            builder: function () use ($customer) {
                return view('components.products-widget', [
                    'products' => $customer->products()->orderBy('name')->get()
                ])->render();
            },
            variant: 'products_widget',
            version: 'v1'
        );

        return view('dashboard.index', ['productsWidgetHtml' => $html]);
    }
}

Livewire Integration

Perfect for caching expensive Livewire component rendering:

Using the Trait (Recommended)

<?php

namespace App\Livewire\Dashboard;

use App\Models\Product;
use Illuminate\Support\HtmlString;
use Iperamuna\HtmlFragmentCache\Concerns\Livewire\CachesRenderedHtml;
use Livewire\Component;
use Livewire\Livewire;

class ActiveProducts extends Component
{
    use CachesRenderedHtml;

    public function render()
    {
        // This will short-circuit on cache hit. The closure only runs on a cache MISS.
        return $this->renderCached(function () {
            // Query (only on cache miss)
            $products = Product::all();

            // Render each row ONCE into HTML (only when building cache)
            $items = $products->map(
                fn ($p) => Livewire::mount('dashboard.active-product', ['product' => $p])
            )->implode('');

            // Render your dashboard-section wrapper and inject the items into the slot
            return view('components.dashboard-section', [
                'title' => 'Active Products',
                'url'   => url('/dashboard/products'),
            ])->with('slot', new HtmlString($items));
        },
            // optional overrides (you can omit these to fully rely on config defaults)
            identifier: 'organization:'. auth()->user()->current_organization_id,                       // null → resolve via config (customer/org)
            variant: 'dashboard_active_products',   // bucket
            version: 'v1',                          // bump on markup change
            ttl: '6 hours'                          // or int/DateInterval
        );
    }
}

Using the Facade

<?php

namespace App\Livewire\Dashboard;

use Livewire\Component;
use FragmentCache;

class ActiveProducts extends Component
{
    public string $identifier; // e.g., 'customer:123'

    public function mount(string $identifier): void
    {
        $this->identifier = $identifier;
    }

    public function render()
    {
        $html = FragmentCache::rememberHtml(
            identifier: $this->identifier,
            builder: function () {
                $products = \App\Models\Product::query()
                    ->where('is_active', true)
                    ->orderBy('name')
                    ->get();

                $items = $products->map(function ($product) {
                    return \Livewire\Livewire::mount('dashboard.active-product', ['product' => $product])->html();
                })->implode('');

                return view('livewire.dashboard.active-products', ['itemsHtml' => $items])->render();
            },
            ttl: '6 hours',
            variant: 'active_products_widget',
            version: 'v1'
        );

        return view('livewire.dashboard.active-products-cached', ['html' => $html]);
    }
}

Cache Invalidation

Forget Specific Fragments

// Forget by identifier
FragmentCache::forget("customer:{$customerId}", variant: 'products_widget_html');

// Forget with version
FragmentCache::forget("customer:{$customerId}", variant: 'products_widget_html', version: 'v1');

Artisan Commands

The package provides interactive Artisan commands for cache management:

# Interactive cache management
php artisan fragment-cache:forget

The fragment-cache:forget command provides three modes:

• Forget by Identifier: Remove specific cached fragments
• Forget by Pattern: Clear fragments matching a pattern (flushes entire cache store)
• Flush All: Clear all fragments from the configured cache store

Advanced Usage

Custom Identifier Resolution

You can customize how identifiers are resolved by modifying the configuration or creating a custom resolver:

// Custom resolver
class CustomIdentifierResolver implements IdentifierResolver
{
    public function resolve(?object $context = null): ?string
    {
        // Your custom logic here
        return 'custom:identifier';
    }
}

Multiple Cache Stores

You can use different cache stores for different environments:

# Development
FRAGMENT_CACHE_STORE=array

# Staging
FRAGMENT_CACHE_STORE=file

# Production
FRAGMENT_CACHE_STORE=redis

Performance Benefits

• Skip Database Queries: Cache the final rendered HTML, not just database results
• Skip Blade Rendering: Avoid expensive view compilation on cache hits
• Universal Compatibility: Works with any Laravel cache driver
• Memory Efficient: Uses Laravel's built-in cache system

Testing

composer test

The test suite uses Orchestra Testbench with the array cache driver for portability.

Requirements

• PHP 8.2+
• Laravel 10.0+ | 11.0+ | 12.0+
• Laravel Prompts (for interactive commands)

Cache Driver Support

Contributing

Please see CONTRIBUTING.md for details.

Security

If you discover any security related issues, please email iperamuna@gmail.com instead of using the issue tracker.

Credits

• Indunil Peramuna
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Changelog

Please see CHANGELOG.md for more information on what has changed recently.

Made with ❤️ for the Laravel community