PHPackages                             imsus/laravel-imgproxy - 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. [Image & Media](/categories/media)
4. /
5. imsus/laravel-imgproxy

ActiveLibrary[Image & Media](/categories/media)

imsus/laravel-imgproxy
======================

High-performance, secure image processing for Laravel. Seamlessly generate signed imgproxy URLs to resize, crop, and transform images on the fly.

v1.1.0(4mo ago)4793—0%3[8 issues](https://github.com/imsus/laravel-imgproxy/issues)MITPHPPHP ^8.2CI passing

Since Aug 29Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/imsus/laravel-imgproxy)[ Packagist](https://packagist.org/packages/imsus/laravel-imgproxy)[ Docs](https://github.com/imsus/laravel-imgproxy)[ GitHub Sponsors](https://github.com/sponsors/imsus)[ RSS](/packages/imsus-laravel-imgproxy/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (10)Versions (19)Used By (0)

[![Analytics Pixel](https://camo.githubusercontent.com/1afddc701ee28a1ac135e3a6d50fa29eb95d726fab125dd1cbb3e460835c2d3c/68747470733a2f2f636c6f75642e756d616d692e69732f702f4578303030766f4a44)](https://camo.githubusercontent.com/1afddc701ee28a1ac135e3a6d50fa29eb95d726fab125dd1cbb3e460835c2d3c/68747470733a2f2f636c6f75642e756d616d692e69732f702f4578303030766f4a44)

   ![Laravel imgproxy banner](https://github.com/user-attachments/assets/71b48db1-7d28-426f-b803-f4f69b3b70b2)Laravel imgproxy
================

[](#laravel-imgproxy)

[![Latest Version on Packagist](https://camo.githubusercontent.com/00f97d75700038b265ecc2fdcc680b3837905aaf6513c362ce86c98b88a45881/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f696d7375732f6c61726176656c2d696d6770726f78792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/imsus/laravel-imgproxy)[![GitHub Tests Action Status](https://camo.githubusercontent.com/6c8056c44587b798383ea6e61acadc3855db181773fdcd444509cee938b7daf7/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f696d7375732f6c61726176656c2d696d6770726f78792f63692e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/imsus/laravel-imgproxy/actions?query=workflow%3Aci+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/5056bb46d2dea89b1f2ae7a04f5fe33503f3408286a4e9fc7885e119ac8dd355/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f696d7375732f6c61726176656c2d696d6770726f78792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/imsus/laravel-imgproxy)

A Laravel package for [imgproxy](https://imgproxy.net/) integration. Generate optimized, signed image URLs with a fluent API.

Use Case
--------

[](#use-case)

Imagine you run an e-commerce platform with thousands of product images. Pages load slowly, cart abandonment rises, and hosting costs climb because every image is served at full resolution. The marketing team needs the same hero image in multiple aspect ratios for different campaigns, but waiting for designers to resize manually slows everything down.

This package solves both problems. Images are resized and compressed on-the-fly—thumbnail, medium, and hero versions generated from a single source. WebP and AVIF formats are served automatically based on browser support, reducing bandwidth by up to 50%. The fluent API lets you chain resizing, quality, and effects in a single readable line, so developers ship faster and users get faster pages.

Why This Package?
-----------------

[](#why-this-package)

You can call imgproxy's raw API directly, but you'd repeat boilerplate code across every project: URL signing logic, configuration loading, enum types, validation, and error handling. This package wraps all that in a clean Laravel package. You get type-safe enums for resize modes and formats, fluent chainable methods that read like sentences, and Laravel-specific conveniences like facades, helpers, and Blade components. The 99.4% test coverage means you can trust it in production. If you're already using Laravel, this feels native—no learning curve, just `imgproxy()->build()` and you're done.

Features
--------

[](#features)

- **Fluent API** - Chainable methods for building image URLs
- **HMAC Signing** - Secure URL signing with configurable key/salt
- **Blade Components** - Ready-to-use Img and Picture components
- **Type Safe** - PHP 8.2+ enums for all options
- **Well Tested** - 99.2% test coverage

Quick Glance
------------

[](#quick-glance)

### Helper Function

[](#helper-function)

```
imgproxy('https://example.com/image.jpg')
    ->setWidth(800)
    ->setHeight(600)
    ->setResizeType(ResizeType::FILL)
    ->setExtension(OutputExtension::WEBP)
    ->setQuality(85)
    ->setBlur(2.0)
    ->setSharpen(1.0)
    ->setDpr(2)
    ->build();

// Output: http://imgproxy.local/signature/width:800/height:600/.../image.webp
```

### Facade

[](#facade)

```
use Imsus\ImgProxy\Facades\ImgProxy;

ImgProxy::url('https://example.com/image.jpg')
    ->setWidth(800)
    ->setHeight(600)
    ->build();

// Output: http://imgproxy.local/signature/width:800/height:600/plain/https://example.com/image.jpg@jpeg
```

### Blade Components

[](#blade-components)

```
{{-- Single image --}}

{{-- Output:

--}}

{{-- Responsive with multiple formats --}}

{{-- Output:

--}}
```

### Laravel Storage Integration

[](#laravel-storage-integration)

Seamless integration with Laravel's Storage facade for both public and private disks:

```
use Illuminate\Support\Facades\Storage;

// Public disk - uses disk->url()
Storage::disk('public')->imgproxy('avatars/user.jpg')
    ->width(300)
    ->height(200)
    ->webp()
    ->build();

// Private disk (S3) - automatically uses temporaryUrl()
Storage::disk('s3')->imgproxy('products/image.jpg')
    ->width(800)
    ->height(600)
    ->cover()
    ->build();
```

The macro automatically detects disk visibility and generates the appropriate URLs (presigned URLs for private disks).

Quick Start
-----------

[](#quick-start)

### Prerequisites

[](#prerequisites)

Before using this package, you need to have [imgproxy](https://imgproxy.net/) set up and running. You can either:

- Use a hosted imgproxy service
- Run imgproxy locally using Docker
- Deploy imgproxy to your preferred cloud platform

Make sure you have your imgproxy URL and signing credentials ready.

### Installation

[](#installation)

```
composer require imsus/laravel-imgproxy
php artisan vendor:publish --tag="laravel-imgproxy-config"
```

```
use Imsus\ImgProxy\Enums\ResizeType;
use Imsus\ImgProxy\Enums\OutputExtension;

$url = imgproxy('https://example.com/image.jpg')
    ->setWidth(800)
    ->setHeight(600)
    ->setResizeType(ResizeType::FILL)
    ->setExtension(OutputExtension::WEBP)
    ->setQuality(85)
    ->build();
```

Documentation
-------------

[](#documentation)

Full documentation available at **[imsus.github.io/laravel-imgproxy](https://imsus.github.io/laravel-imgproxy/)**:

- **[Getting Started](https://imsus.github.io/laravel-imgproxy/guide/getting-started)** - Introduction and requirements
- **[Installation](https://imsus.github.io/laravel-imgproxy/guide/installation)** - Setup and configuration
- **[Usage Guide](https://imsus.github.io/laravel-imgproxy/guide/usage)** - Basic usage patterns
- **[Resizing](https://imsus.github.io/laravel-imgproxy/guide/resizing)** - Resize modes, gravity, DPR
- **[Quality & Format](https://imsus.github.io/laravel-imgproxy/guide/quality)** - Output settings
- **[Visual Effects](https://imsus.github.io/laravel-imgproxy/guide/effects)** - Blur and sharpen
- **[Blade Components](https://imsus.github.io/laravel-imgproxy/guide/blade-components)** - Img and Picture components
- **[Advanced Usage](https://imsus.github.io/laravel-imgproxy/guide/advanced-usage)** - Laravel integration patterns
- **[API Reference](https://imsus.github.io/laravel-imgproxy/reference/api)** - Complete method reference
- **[Enums Reference](https://imsus.github.io/laravel-imgproxy/reference/enums)** - Type-safe enums
- **[Security](https://imsus.github.io/laravel-imgproxy/guide/security)** - Best practices
- **[Testing](https://imsus.github.io/laravel-imgproxy/contribute/testing)** - Running tests

Configuration
-------------

[](#configuration)

Publish the config file and configure via `.env`:

```
php artisan vendor:publish --tag="laravel-imgproxy-config"
```

```
IMGPROXY_ENDPOINT=http://localhost:8080
IMGPROXY_KEY=
IMGPROXY_SALT=
IMGPROXY_DEFAULT_SOURCE_URL_MODE=encoded
IMGPROXY_DEFAULT_OUTPUT_EXTENSION=jpeg
IMGPROXY_DEFAULT_GRAVITY=ce
```

OptionDescriptionDefault`IMGPROXY_ENDPOINT`Your imgproxy server URL`http://localhost:8080``IMGPROXY_KEY`HMAC signing key`null``IMGPROXY_SALT`HMAC salt`null``IMGPROXY_DEFAULT_SOURCE_URL_MODE`Default source URL mode (`encoded` or `raw`)`encoded``IMGPROXY_DEFAULT_OUTPUT_EXTENSION`Default output format (`jpeg`, `png`, `webp`, `avif`, `gif`)`jpeg``IMGPROXY_DEFAULT_GRAVITY`Default gravity (`ce`, `no`, `so`, `ea`, `we`, `ce`, `c`, `f`)`ce`If no key/salt is configured, URLs will be generated unsigned.

### Generating Keys

[](#generating-keys)

Generate secure signing keys automatically:

```
php artisan imgproxy:key
```

This command generates 64-character hex strings for `IMGPROXY_KEY` and `IMGPROXY_SALT`, saves them to your `.env` file, and displays them in the console.

Troubleshooting
---------------

[](#troubleshooting)

### Signature verification failed

[](#signature-verification-failed)

- Verify `IMGPROXY_KEY` and `IMGPROXY_SALT` match your imgproxy server configuration
- Ensure encoding (hex vs base64) is consistent between your app and imgproxy server

### URLs not generating

[](#urls-not-generating)

- Check that `IMGPROXY_ENDPOINT` is accessible from your application
- Validate the source URL is publicly accessible or allowlisted in imgproxy

### Images loading slowly

[](#images-loading-slowly)

- Enable DPR for retina displays: `->setDpr(2)`
- Use `OutputExtension::AVIF` for best compression
- Consider lower quality for smaller file sizes: `->setQuality(75)`

Changelog
---------

[](#changelog)

See [CHANGELOG.md](CHANGELOG.md) for version history and breaking changes.

Commands
--------

[](#commands)

```
composer test          # Run tests
composer test-coverage # Run tests with coverage
composer format        # Format code
composer start         # Start workbench server

php artisan imgproxy:key  # Generate IMGPROXY_KEY and IMGPROXY_SALT
```

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE.md) for details.

Laravel is a trademark of .

imgproxy is a trademark of .

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance63

Regular maintenance activity

Popularity24

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 79.4% of commits — single point of failure

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

Every ~33 days

Recently: every ~0 days

Total

16

Last Release

137d ago

Major Versions

v0.10.0 → v1.0.02026-01-01

### Community

Maintainers

![](https://www.gravatar.com/avatar/3524abb392631dcfd2d7d099ab825a202a50190706a1e1eeb392cac03dadde67?d=identicon)[imsus](/maintainers/imsus)

---

Top Contributors

[![imsus](https://avatars.githubusercontent.com/u/1058471?v=4)](https://github.com/imsus "imsus (158 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (19 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (13 commits)")[![yoomarket](https://avatars.githubusercontent.com/u/158214263?v=4)](https://github.com/yoomarket "yoomarket (5 commits)")[![cto-new[bot]](https://avatars.githubusercontent.com/in/364074?v=4)](https://github.com/cto-new[bot] "cto-new[bot] (3 commits)")[![felixdorn](https://avatars.githubusercontent.com/u/55788595?v=4)](https://github.com/felixdorn "felixdorn (1 commits)")

---

Tags

imgproxylaravellaravel-imgproxyphplaravelthumbnailimageimage processingwatermarkimage resizecropimgproxy

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/imsus-laravel-imgproxy/health.svg)

```
[![Health](https://phpackages.com/badges/imsus-laravel-imgproxy/health.svg)](https://phpackages.com/packages/imsus-laravel-imgproxy)
```

###  Alternatives

[sybio/image-workshop

Powerful PHP class using GD library to work easily with images including layer notion (like Photoshop or GIMP)

860918.1k11](/packages/sybio-image-workshop)[intervention/image-laravel

Laravel Integration of Intervention Image

1536.5M102](/packages/intervention-image-laravel)[jbzoo/image

A PHP class that simplifies working with images

171126.9k3](/packages/jbzoo-image)[danihidayatx/image-optimizer

Optimize your Filament images before they reach your database. Forked from joshembling/image-optimizer for Filament v4 & v5 support.

254.4k](/packages/danihidayatx-image-optimizer)

PHPackages © 2026

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