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(1w ago)10MITPHPPHP ^8.2CI passing

Since Mar 13Pushed 1w 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 today

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

39

—

LowBetter than 87% of packages

Maintenance98

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity45

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

9d 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.8k7.9M42](/packages/spatie-laravel-responsecache)[intervention/image-laravel

Laravel Integration of Intervention Image

1445.8M73](/packages/intervention-image-laravel)[bkwld/croppa

Image thumbnail creation through specially formatted URLs for Laravel

508489.5k18](/packages/bkwld-croppa)[antennaio/laravel-clyde

Image uploads and manipulation for Laravel, a wrapper around Glide

302.6k](/packages/antennaio-laravel-clyde)[michele-angioni/support

Support is a Laravel package which promotes the use of best practices and design patterns.

181.4k1](/packages/michele-angioni-support)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
