Download the PHP package rafoabbas/laravel-image-proxy without Composer

Laravel Image Proxy

On-the-fly image transformation, AVIF/WebP conversion, and caching proxy for Laravel.

Features

• Automatic AVIF/WebP conversion with content negotiation (Accept header)
• Resize, crop, and quality control via query parameters
• Visual effects: blur, sharpen, grayscale, brightness, contrast
• Rotation and flip (horizontal, vertical, both)
• Watermark overlay with configurable position, opacity, and size
• Focal point crop for smart cropping around a point of interest
• Border radius (rounded corners) and padding with background color
• LQIP (Low Quality Image Placeholder) support
• Signed URLs with HMAC-SHA256 for abuse prevention
• GD and Imagick driver support
• Disk-based caching with configurable storage backend
• Cache locking to prevent duplicate processing
• Memory guard to reject oversized images
• External URL proxying with domain allowlist and SSRF protection
• Remote disk (S3, R2, GCS) original caching to reduce repeated downloads
• ImageProxy facade and @imageSrcset Blade directive
• Artisan command for cache management (age-based, size-based cleanup)
• Supports Laravel 10, 11, 12, and 13

Requirements

• PHP 8.2+
• GD extension (ext-gd) or Imagick extension (ext-imagick)
• Laravel 10.x / 11.x / 12.x / 13.x

Installation

The package auto-discovers its service provider. Publish the config file:

Configuration

After publishing, edit config/image-proxy.php:

Usage

Basic

Once installed, images are served through the /img/{path} route:

This reads photos/landscape.jpg from the configured source disk, converts it to the best format supported by the client (AVIF > WebP), caches the result, and returns it with proper Cache-Control, ETag, Vary, and Content-Type headers.

Query Parameters

Examples:

Effects

Apply visual effects to any image:

Combine effects with resize:

Rotation & Flip

The bg parameter sets the background color for areas exposed by rotation. Defaults to white.

Watermark

Overlay a watermark image on any processed image:

Watermark positions: top-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right

Watermark images are read from the watermark_disk (falls back to source_disk). Returns 404 if the watermark file doesn't exist.

Focal Point Crop

Crop around a specific point of interest instead of the center:

Both focal_x and focal_y must be provided along with w and h. Values are clamped to 0.0–1.0, where (0,0) is the top-left corner and (1,1) is the bottom-right.

Border Radius & Padding

Add rounded corners and padding:

Generating URLs

Using the Facade

When URL signing is enabled, all URLs generated through the facade are automatically signed.

Using the Blade Directive

This generates a complete <img> tag with srcset, sizes, loading="lazy", and decoding="async" attributes.

Using Route Helper

Note: The route helper does not support signed URLs. Use the ImageProxy facade when signing is enabled.

URL Signing

Enable signed URLs to prevent unauthorized transformations:

When enabled, all requests must include a valid s parameter. URLs without a valid signature receive a 403 response.

Content Negotiation (AVIF/WebP)

The proxy automatically selects the best output format based on the client's Accept header:

1. If the client supports AVIF and 'avif' is in the formats config → serves AVIF
2. If the client supports WebP and 'webp' is in the formats config → serves WebP
3. Falls back to the last format in the list

The response includes a Vary: Accept header for proper CDN caching.

Note: AVIF encoding with the GD driver requires PHP 8.1+ with libavif. The Imagick driver provides more reliable AVIF support.

LQIP (Low Quality Image Placeholder)

Request a tiny placeholder image for lazy loading:

This returns a 20px wide, quality-20 thumbnail (typically under 1KB) that can be used as a blur-up placeholder.

External URL Proxying

Add allowed domains to the config:

Then pass the full URL as the path:

The proxy includes SSRF protection: localhost, private IPs, and reserved ranges are blocked.

Remote Disk Caching

When using remote disks like S3 or R2 as the source, originals are automatically cached to the local cache disk. This avoids re-downloading the same file on subsequent requests with different transformation parameters.

Disable with 'cache_remote_originals' => false in the config.

Rate Limiting

The package does not include built-in rate limiting. Use Laravel's throttle middleware on the image proxy route:

Or apply more granular throttling with a custom rate limiter:

Cache Management

Clear the cache using the Artisan command:

Testing

Code Style

License

MIT