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(7mo ago)81.3k↑168.8%5MITPHPPHP ^8.2CI passing Since Aug 29Pushed 1w 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 2w ago READMEChangelog (10)Dependencies (10)Versions (20)Used By (0) Laravel imgproxy ================ [](#laravel-imgproxy) [![Packagist](https://camo.githubusercontent.com/00f97d75700038b265ecc2fdcc680b3837905aaf6513c362ce86c98b88a45881/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f696d7375732f6c61726176656c2d696d6770726f78792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/imsus/laravel-imgproxy) [![PHP from Packagist](https://camo.githubusercontent.com/a047ddc2ad0a5af40762e7e81a8851e9683b6ccc24ad76ee2bbd25931aec6fe0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f696d7375732f6c61726176656c2d696d6770726f78792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/imsus/laravel-imgproxy) [![Laravel versions](https://camo.githubusercontent.com/67d87ac448a2847c29a9bf0b34fb1139877de66a9b1863df7d4583a42e761767/68747470733a2f2f62616467652e6c61726176656c2e636c6f75642f62616467652f696d7375732f6c61726176656c2d696d6770726f78793f7374796c653d666c6174)](https://packagist.org/packages/imsus/laravel-imgproxy) [![GitHub Workflow Status (main)](https://camo.githubusercontent.com/1e53f8d95a04398042629fdb9629beece5febd39c0697715e14107027dfcac09/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f696d7375732f6c61726176656c2d696d6770726f78792f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d5465737473267374796c653d666c61742d737175617265)](https://github.com/imsus/laravel-imgproxy/actions) [![Total Downloads](https://camo.githubusercontent.com/5056bb46d2dea89b1f2ae7a04f5fe33503f3408286a4e9fc7885e119ac8dd355/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f696d7375732f6c61726176656c2d696d6770726f78792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/imsus/laravel-imgproxy) imgproxy integration for Laravel. Generate signed, processed image URLs with an immutable fluent builder, render responsive `` and `` tags with LQIP placeholders, and build sources from any Storage disk — public disks get plain URLs, private disks get pre-signed temporary URLs. Requirements ------------ [](#requirements) - PHP ^8.4 - Laravel 13 - An imgproxy server (v4 recommended; the option segments target the v4 processing docs) Installation ------------ [](#installation) You can install the package via Composer: ``` composer require imsus/laravel-imgproxy:^2.0 ``` > **Using 1.x?** v1 stays available. Pin `^1.0` to keep the last 1.x release, or `1.x-dev` for the maintenance branch. v1 requires PHP ^8.2 and Laravel 10–12; v2 requires PHP ^8.4 and Laravel 13. The v1 source lives on the [`1.x` branch](https://github.com/imsus/laravel-imgproxy/tree/1.x), and its Packagist versions remain published. Migrating? See [UPGRADING](UPGRADING.md). Publish the configuration file: ``` php artisan vendor:publish --tag="laravel-imgproxy-config" ``` You may publish all of the package's resources at once: ``` php artisan vendor:publish --tag="laravel-imgproxy" ``` The component templates publish to `resources/views/vendor/imgproxy` (the `laravel-imgproxy-views` tag) and override the package defaults. Configuration ------------- [](#configuration) The default instance reads its connection details from the environment, so the package works after setting three variables: ``` IMGPROXY_URL=https://imgproxy.example.com IMGPROXY_KEY=943b421c9eb07c830af81030552c86009268de4e532ba2ee2eab8247c6da0881 IMGPROXY_SALT=520f986b998545b4785e0defbc4f3c1203f22de2374a3d53cb7a7fe9fea309c5 ``` `IMGPROXY_KEY` and `IMGPROXY_SALT` are the hex-encoded values configured on the imgproxy server. When they are absent, URLs are generated unsigned with an `unsafe` signature slot — fine for local development, but configure them for anything exposed to the internet. Use `php artisan imgproxy:key` to generate a fresh pair. The published `config/laravel-imgproxy.php` supports multiple named instances, each with its own server, credentials, signature size, and encoding: ``` 'instances' => [ 'default' => [ 'url' => env('IMGPROXY_URL'), 'key' => env('IMGPROXY_KEY'), 'salt' => env('IMGPROXY_SALT'), 'signature_size' => null, 'encoding' => 'base64', ], 'staging' => [ 'url' => 'https://imgproxy-staging.example.com', 'key' => '...', 'salt' => '...', 'signature_size' => 16, // match IMGPROXY_SIGNATURE_SIZE on the server 'encoding' => 'base64', ], ], ``` Per-instance options: - `url` — base URL of the imgproxy server, without a trailing slash. - `key` / `salt` — hex-encoded HMAC credentials; `null` generates unsigned URLs. - `signature_size` — signature bytes to keep (1–32), matching the server's `IMGPROXY_SIGNATURE_SIZE`; `null` keeps the full digest. - `encoding` — source encoding: `base64` (URL-safe, no padding, the default) or `plain` (percent-encoded source behind a `plain/` prefix). Named presets — reusable sets of processing options defined in config and shared across instances — are also supported. See the [documentation](#documentation) for details. Quick Start ----------- [](#quick-start) The `Imgproxy` facade and the `imgproxy()` helper both resolve the default instance: ``` use Imsus\LaravelImgproxy\Imgproxy; use Imsus\LaravelImgproxy\Enums\Format; use Imsus\LaravelImgproxy\Enums\Gravity; use Imsus\LaravelImgproxy\Enums\ResizeType; use Imsus\LaravelImgproxy\Enums\WatermarkPosition; $url = Imgproxy::image('https://example.com/image.jpg') ->resize(ResizeType::Fill, 300, 300) ->quality(80) ->format(Format::Webp) ->url(); // https://imgproxy.example.com/unsafe/rs:fill:300:300/q:80/f:webp/aHR0cHM6Ly9leGFtcGxlLmNvbS9pbWFnZS5qcGc ``` Every imgproxy v4 processing option has one typed, validating method — resize, crop, gravity, blur, watermark, format, and more — and enum arguments accept the enum or its string value interchangeably (`Gravity::Smart` and `'sm'` produce the same URL). For options not yet covered, `withOption()` appends a segment verbatim. `url()` and `__toString()` return the full URL; either works as a terminal call. Because builders are immutable, every mutation returns a new instance. A base builder can be reused for several variants without accidental mutation: ``` $base = Imgproxy::image('https://example.com/image.jpg')->quality(80); $small = $base->width(320)->url(); $large = $base->width(1280)->url(); // quality:80 still applies; no width leak from $small ``` ### Signing [](#signing) With a key and salt configured, the `unsafe` slot is automatically replaced by an HMAC-SHA256 signature: ``` // https://imgproxy.example.com/7Fu-sZuoCXRc1LXWhM687mlhsd2SFxXBpiFjJk6vakw/rs:fill:300:300/... ``` The signature covers the exact path emitted, so encoding choice and signing are computed together. `signature_size` truncates the signature to match the server; an empty key or salt disables signing. ### Storage Disks [](#storage-disks) Sources can come from any Laravel Storage disk. Public disks yield the disk's `url()`; private disks yield a pre-signed `temporaryUrl()`: ``` use Illuminate\Support\Facades\Storage; // Public disk -> url() Storage::disk('public')->imgproxy('images/photo.jpg') ->width(800) ->format(Format::Webp) ->url(); // Private disk (S3) -> pre-signed temporaryUrl(), 5 minutes by default Storage::disk('s3')->imgproxy('products/image.jpg', 3600) ->resize(ResizeType::Fill, 800, 600) ->url(); ``` Blade Components ---------------- [](#blade-components) The package ships two Blade components: `` for a single `` with responsive srcsets, and `` for format negotiation with a fallback image. Both support LQIP placeholders, width or DPR candidates, named presets, lazy loading by default, and Storage disk sources: ``` ``` Artisan Commands ---------------- [](#artisan-commands) ### `imgproxy:key` [](#imgproxykey) Generates a fresh 32-byte key and salt pair for URL signing, printed as environment lines ready for `.env`: ``` php artisan imgproxy:key Generated a new imgproxy key and salt pair. IMGPROXY_KEY=... IMGPROXY_SALT=... ``` The command never writes to `.env` itself. ### `imgproxy:health` [](#imgproxyhealth) Checks an instance's `/health` endpoint and exits non-zero when the instance is unreachable, unhealthy, or not configured: ``` php artisan imgproxy:health # default instance php artisan imgproxy:health --instance=staging ``` Documentation ------------- [](#documentation) The full documentation — every option method, the enums, presets, security, storage integration, and troubleshooting — is available at , with the source in [`docs/`](docs/). Testing Against a Real imgproxy ------------------------------- [](#testing-against-a-real-imgproxy) The test suite includes live checks against a real imgproxy running locally in Docker. They are gated behind three environment variables and skip when they are not set (CI never sets them): ``` IMGPROXY_URL=http://localhost:8081 IMGPROXY_KEY=0000000000000000000000000000000000000000000000000000000000000000 IMGPROXY_SALT=0000000000000000000000000000000000000000000000000000000000000000 ``` The key and salt must match the local server's `IMGPROXY_KEY` / `IMGPROXY_SALT`. With the variables exported, the live tests run as part of `composer test`. Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Upgrading from 1.x? See [UPGRADING](UPGRADING.md). Contributing ------------ [](#contributing) Thank you for considering contributing to Laravel imgproxy! Please review our [contributing guide](.github/CONTRIBUTING.md) to get started. Security Vulnerabilities ------------------------ [](#security-vulnerabilities) Please review [our security policy](.github/SECURITY.md) on how to report security vulnerabilities. Credits ------- [](#credits) - [Imam Susanto](https://github.com/imsus) - [All Contributors](../../contributors) License ------- [](#license) Laravel imgproxy is open-sourced software licensed under the [MIT license](LICENSE.md). ### Health Score 50 — FairBetter than 95% of packages Maintenance83 Actively maintained with recent releases Popularity27 Limited adoption so far Community16 Small or concentrated contributor base Maturity62 Established project with proven stability Bus Factor2 2 contributors hold 50%+ of commits 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 229d 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 [![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (37 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (31 commits)")[![imsus](https://avatars.githubusercontent.com/u/1058471?v=4)](https://github.com/imsus "imsus (31 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 [dedoc/scramble Automatic generation of API documentation for Laravel applications. 2.2k12.6M141](/packages/dedoc-scramble)[rawilk/profile-filament-plugin Profile & MFA starter kit for filament. 3915.5k](/packages/rawilk-profile-filament-plugin)[harris21/laravel-fuse Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures. 46273.9k](/packages/harris21-laravel-fuse)[vormkracht10/laravel-mails Laravel Mails can collect everything you might want to track about the mails that has been sent by your Laravel app. 25060.1k](/packages/vormkracht10-laravel-mails)[finller/laravel-media A flexible media library for Laravel 472.1k](/packages/finller-laravel-media)[danihidayatx/image-optimizer Optimize your Filament images before they reach your database. Forked from joshembling/image-optimizer for Filament v4 & v5 support. 3423.0k1](/packages/danihidayatx-image-optimizer) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)