PHPackages jcfrane/laravel-lens - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Caching](/categories/caching) 4. / 5. jcfrane/laravel-lens ActiveLibrary[Caching](/categories/caching) jcfrane/laravel-lens ==================== Configuration-driven image manipulation and caching for Laravel, inspired by LiipImagineBundle v1.0.0(2mo ago)10MITPHPPHP ^8.2CI passing Since Mar 13Pushed 2mo agoCompare [ Source](https://github.com/jcfrane/laravel-lens)[ Packagist](https://packagist.org/packages/jcfrane/laravel-lens)[ RSS](/packages/jcfrane-laravel-lens/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)Dependencies (10)Versions (2)Used By (0) Laravel Lens ============ [](#laravel-lens) [![Latest Version on Packagist](https://camo.githubusercontent.com/3081b8f29319897027098e510e271de229f4860885df81d5c970d5df02ecd141/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a636672616e652f6c61726176656c2d6c656e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jcfrane/laravel-lens)[![GitHub Tests Action Status](https://camo.githubusercontent.com/c193af21f7927712276709be6d3accce94e3a3cc61176f98d464ba7990895700/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6a636672616e652f6c61726176656c2d6c656e732f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/jcfrane/laravel-lens/actions?query=workflow%3Atests+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/43c01166f68c9935fec2e308e287d72b72bbc4a6541e8db5cf5349546c3db4c1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a636672616e652f6c61726176656c2d6c656e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jcfrane/laravel-lens)[![License](https://camo.githubusercontent.com/6a2151a494a3c03e6afa3ce301a2e2d299288de2b1584837c346a01feaf9e9bd/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6a636672616e652f6c61726176656c2d6c656e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jcfrane/laravel-lens) Configuration-driven image manipulation and caching for Laravel, inspired by Symfony's [LiipImagineBundle](https://github.com/liip/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](https://image.intervention.io/) and Laravel's filesystem abstraction, it works with any storage driver out of the box. Quick Examples -------------- [](#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 // Blade component // Facade $url = Lens::url('photos/profile.jpg', 'avatar'); // API route (auto-registered) // GET /lens/avatar/photos/profile.jpg ``` Features -------- [](#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 `` 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 ------------ [](#requirements) - PHP 8.2+ - Laravel 12 - GD or Imagick PHP extension Installation ------------ [](#installation) ``` composer require jcfrane/laravel-lens ``` Publish the configuration file: ``` php artisan vendor:publish --tag=lens-config ``` Configuration ------------- [](#configuration) The published config file (`config/lens.php`) contains all settings: ### Driver [](#driver) ``` 'driver' => env('LENS_DRIVER', 'gd'), // 'gd' or 'imagick' ``` ### Data Loader [](#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 [](#cache) Configure where processed images are stored: ``` 'cache' => [ 'default' => 'filesystem', 'resolvers' => [ 'filesystem' => [ 'driver' => 'filesystem', 'disk' => env('LENS_CACHE_DISK', 'public'), 'base_path' => 'lens-cache', ], ], ], ``` ### Filter Sets [](#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 [](#routes) ``` 'route' => [ 'enabled' => true, 'prefix' => 'lens', 'middleware' => ['web'], 'signed' => false, ], ``` Usage ----- [](#usage) ### Blade Directive [](#blade-directive) ``` ``` ### Blade Component [](#blade-component) ``` ``` The component renders an `` tag with the filtered image URL and passes through any additional HTML attributes. ### Facade [](#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'); // Invalidate cached images Lens::invalidate('photos/landscape.jpg'); Lens::invalidate('photos/landscape.jpg', ['thumbnail_small']); ``` ### Runtime Filter Overrides [](#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 [](#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 ----------------- [](#available-filters) FilterOptionsDescription`auto_orient`—Rotate based on EXIF orientation data`thumbnail``size`, `mode`, `upscale`Scale and/or crop to thumbnail dimensions`crop``size`, `start`Crop a rectangular region`resize``size`Resize to exact dimensions`scale``size`Scale proportionally`watermark``image`, `position`, `opacity`, `size`Overlay a watermark image`grayscale`—Convert to grayscale`flip``direction`Mirror horizontally or vertically`rotate``angle`, `background`Rotate by degrees`blur``amount`Apply Gaussian blur`brightness``level`Adjust brightness (-100 to 100)`contrast``level`Adjust contrast (-100 to 100)`background``color`, `size`, `position`Set or extend canvas with background color`strip`—Remove animation framesCustom 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 ---------------- [](#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 ------- [](#testing) ``` composer test ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. Security -------- [](#security) If you discover any security-related issues, please use the issue tracker. Credits ------- [](#credits) - [JC Frane](https://github.com/jcfrane) - [All Contributors](../../contributors) Acknowledgments --------------- [](#acknowledgments) - [LiipImagineBundle](https://github.com/liip/LiipImagineBundle) — the Symfony bundle that inspired this package - [Intervention Image](https://image.intervention.io/) — the underlying image processing library License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE) for more information. ### Health Score 37 — LowBetter than 83% of packages Maintenance88 Actively maintained with recent releases Popularity2 Limited adoption so far Community2 Small or concentrated contributor base Maturity46 Maturing project, gaining track record How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 60d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/2dfbe5a9ae770e600c736bec7beef2ad46eca3cc19b3cb0a8de9816b615b8c96?d=identicon)[jcfrane](/maintainers/jcfrane) --- Tags laravelthumbnailimagemanipulationresizecachefilter ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/jcfrane-laravel-lens/health.svg) ``` [![Health](https://phpackages.com/badges/jcfrane-laravel-lens/health.svg)](https://phpackages.com/packages/jcfrane-laravel-lens) ``` ### Alternatives [spatie/laravel-responsecache Speed up a Laravel application by caching the entire response 2.8k8.2M51](/packages/spatie-laravel-responsecache)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9682.1M97](/packages/roots-acorn)[laravel/pulse Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application. 1.7k12.1M99](/packages/laravel-pulse)[intervention/image-laravel Laravel Integration of Intervention Image 1496.5M102](/packages/intervention-image-laravel)[bkwld/croppa Image thumbnail creation through specially formatted URLs for Laravel 510496.0k23](/packages/bkwld-croppa)[laravel/folio Page based routing for Laravel. 608453.9k27](/packages/laravel-folio) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)