Download the PHP package imsus/laravel-imgproxy without Composer

Laravel imgproxy

A Laravel package for imgproxy integration. Generate optimized, signed image URLs with a fluent API.

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?

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

• 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

Helper Function

Facade

Blade Components

Laravel Storage Integration

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

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

Quick Start

Prerequisites

Before using this package, you need to have imgproxy 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

Documentation

Full documentation available at imsus.github.io/laravel-imgproxy:

• Getting Started - Introduction and requirements
• Installation - Setup and configuration
• Usage Guide - Basic usage patterns
• Resizing - Resize modes, gravity, DPR
• Quality & Format - Output settings
• Visual Effects - Blur and sharpen
• Blade Components - Img and Picture components
• Advanced Usage - Laravel integration patterns
• API Reference - Complete method reference
• Enums Reference - Type-safe enums
• Security - Best practices
• Testing - Running tests

Configuration

Publish the config file and configure via .env:

If no key/salt is configured, URLs will be generated unsigned.

Generating Keys

Generate secure signing keys automatically:

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

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

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

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

See CHANGELOG.md for version history and breaking changes.

Commands

License

MIT License. See LICENSE for details.

Laravel is a trademark of https://laravel.com/legal/trademark.

imgproxy is a trademark of https://imgproxy.net/.