Download the PHP package jcfrane/laravel-lens without Composer

Laravel Lens

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:

Use them anywhere in your application:

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

Publish the configuration file:

Configuration

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

Driver

Data Loader

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

Cache

Configure where processed images are stored:

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:

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:

Routes

Usage

Blade Directive

Blade Component

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

Facade

Runtime Filter Overrides

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

API Route

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

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:

Register it in a service provider:

Then use it in your filter sets:

Artisan Commands

Testing

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.