README

Configuration-driven image manipulation and caching for Laravel, inspired by Symfony's LiipImagineBundle.

Define named filter sets in your config, and Laravel Lens handles the rest — lazy processing on first request, automatic caching, and simple Blade integration. Built on top of Intervention Image and Laravel's filesystem abstraction, it works with any storage driver out of the box.

Quick Examples

Define filter sets in your config:

// config/lens.php
'filter_sets' => [
    'avatar' => [
        'quality' => 80,
        'filters' => [
            ['name' => 'auto_orient'],
            ['name' => 'thumbnail', 'options' => ['size' => [150, 150], 'mode' => 'outbound']],
        ],
    ],
    'hero_banner' => [
        'quality' => 90,
        'format' => 'webp',
        'filters' => [
            ['name' => 'resize', 'options' => ['size' => [1200, null]]],
            ['name' => 'blur', 'options' => ['amount' => 5]],
        ],
    ],
],

Use them anywhere in your application:

// Blade directive
<img src="@lens('photos/profile.jpg', 'avatar')" alt="Profile" />

// Blade component
<x-lens-image path="photos/hero.jpg" filter="hero_banner" alt="Hero" class="w-full" />

// Facade
$url = Lens::url('photos/profile.jpg', 'avatar');

// API route (auto-registered)
// GET /lens/avatar/photos/profile.jpg

Features

• Configuration-driven filter sets — define once, use everywhere
• 14 built-in filters — thumbnail, crop, resize, scale, watermark, grayscale, flip, rotate, blur, brightness, contrast, background, strip, auto_orient
• Lazy processing — images are processed on first request, then served from cache
• Multiple storage drivers — works with local disk, S3, or any Laravel filesystem driver
• Blade integration — @lens() directive and <x-lens-image /> component
• Built-in API route — /lens/{filterSet}/{path} for on-demand processing
• Cache management — Artisan commands for clearing and warming up the cache
• Multiple drivers — GD and Imagick support via Intervention Image
• Runtime overrides — pass options at call time without creating new filter sets
• Extensible — register custom filters with a simple interface

Requirements

• PHP 8.2+ (PHP 8.3+ for Laravel 13)
• Laravel 12 or 13
• GD or Imagick PHP extension

Installation

composer require jcfrane/laravel-lens

Publish the configuration file:

php artisan vendor:publish --tag=lens-config

Configuration

The published config file (config/lens.php) contains all settings:

Driver

'driver' => env('LENS_DRIVER', 'gd'), // 'gd' or 'imagick'

Data Loader

Configure where source images are loaded from. Uses Laravel filesystem disks:

'data_loader' => [
    'default' => 'filesystem',
    'loaders' => [
        'filesystem' => [
            'driver' => 'filesystem',
            'disk' => env('LENS_SOURCE_DISK', 'public'),
            'base_path' => '',
        ],
    ],
],

Cache

Configure where processed images are stored:

'cache' => [
    'default' => 'filesystem',
    'resolvers' => [
        'filesystem' => [
            'driver' => 'filesystem',
            'disk' => env('LENS_CACHE_DISK', 'public'),
            'base_path' => 'lens-cache',
        ],
    ],
],

Stampede Protection

When a popular image is requested before its variant is cached, many concurrent requests can each decode the full-size source into memory. Enable the lock so only one request runs the pipeline while the rest wait for the cached result:

'lock' => [
    'enabled' => env('LENS_LOCK_ENABLED', false),
    'store' => null,   // Laravel cache store for the atomic lock (null = default)
    'timeout' => 30,   // seconds the generating request may hold the lock
    'wait' => 15,      // seconds concurrent requests wait for the lock
],

Requires a cache store that supports atomic locks (redis, memcached, database, file, array, dynamodb).

Filter Sets

Each filter set defines an ordered pipeline of filters:

'filter_sets' => [
    'thumbnail_small' => [
        'quality' => 80,          // encoding quality (1-100)
        'format' => null,         // null = keep original, or 'webp', 'jpeg', 'png'
        'cache' => null,          // null = use default cache resolver
        'data_loader' => null,    // null = use default data loader
        'filters' => [
            ['name' => 'auto_orient'],
            ['name' => 'thumbnail', 'options' => [
                'size' => [150, 150],
                'mode' => 'outbound',  // 'outbound' (cover) or 'inset' (contain)
            ]],
        ],
    ],
],

Routes

'route' => [
    'enabled' => true,
    'prefix' => 'lens',
    'middleware' => ['web'],
    'signed' => false,
],

Usage

Blade Directive

<img src="@lens('photos/landscape.jpg', 'thumbnail_small')" alt="Landscape" />

Blade Component

<x-lens-image path="photos/landscape.jpg" filter="thumbnail_small" alt="Landscape" class="rounded shadow" />

The component renders an <img> tag with the filtered image URL and passes through any additional HTML attributes.

Facade

use JCFrane\LaravelLens\Facades\Lens;

// Get the URL for a filtered image
$url = Lens::url('photos/landscape.jpg', 'thumbnail_small');

// Process and cache an image immediately
$binary = Lens::resolve('photos/landscape.jpg', 'thumbnail_small');

// Check if a filtered image is cached
$cached = Lens::isCached('photos/landscape.jpg', 'thumbnail_small');

// Where the cached variant lives on the cache disk (null for no_cache)
$path = Lens::cachedPath('photos/landscape.jpg', 'thumbnail_small');
// => 'lens-cache/thumbnail_small/photos/landscape.jpg'

// Stream the cached variant as an HTTP response without loading it into
// memory (null when not cached — generate or fall back yourself)
$response = Lens::cachedResponse('photos/landscape.jpg', 'thumbnail_small', headers: [
    'Cache-Control' => 'public, max-age=31536000, immutable',
]);

// Invalidate cached images
Lens::invalidate('photos/landscape.jpg');
Lens::invalidate('photos/landscape.jpg', ['thumbnail_small']);

Runtime Filter Overrides

Override filter options at call time without creating a new filter set:

$url = Lens::url('photo.jpg', 'thumbnail_small', [
    'thumbnail' => ['size' => [200, 200]],
]);

API Route

The package auto-registers a route for on-demand image processing:

GET /lens/{filterSet}/{path}

On the first request, the image is processed through the filter pipeline and cached. Subsequent requests are served from cache with a redirect.

Example: /lens/thumbnail_small/photos/landscape.jpg

Available Filters

Custom Filters

Create a class implementing FilterInterface:

use Intervention\Image\Interfaces\ImageInterface;
use JCFrane\LaravelLens\Contracts\FilterInterface;

class SepiaFilter implements FilterInterface
{
    public function apply(ImageInterface $image, array $options = []): ImageInterface
    {
        return $image->greyscale()->brightness(-10)->contrast(10);
    }

    public function name(): string
    {
        return 'sepia';
    }
}

Register it in a service provider:

use JCFrane\LaravelLens\Facades\Lens;

Lens::filterManager()->register('sepia', new SepiaFilter());

Then use it in your filter sets:

'filter_sets' => [
    'vintage' => [
        'filters' => [
            ['name' => 'sepia'],
            ['name' => 'blur', 'options' => ['amount' => 2]],
        ],
    ],
],

Artisan Commands

# Clear all cached images
php artisan lens:cache:clear

# Clear cache for a specific filter set
php artisan lens:cache:clear --filter=thumbnail_small

# Clear cache for a specific image
php artisan lens:cache:clear --path=photos/old-image.jpg

# Pre-generate cached images
php artisan lens:cache:warmup --path=photos/hero.jpg --path=photos/logo.png

# Warm up specific filter sets only
php artisan lens:cache:warmup --path=photos/hero.jpg --filter=thumbnail_small --filter=thumbnail_medium

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please use the issue tracker.

Credits

• JC Frane
• All Contributors

Acknowledgments

• LiipImagineBundle — the Symfony bundle that inspired this package
• Intervention Image — the underlying image processing library

License

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