mercator/wn-mresize-plugin

On-demand image and PDF resizing plugin for Winter CMS, providing a drop-in replacement for the resize filter with modern formats and a strict concurrency cap.

dev-main 2026-01-27 22:14 UTC

Requires

• php: >=8.0
• composer/installers: ~1.0
• intervention/image: ^3.0
• league/glide: ^3.1

MIT

• Helmut Kaufmann

• image
• cms
• pdf
• resize
• intervention
• Webp
• winter
• wintercms

README

This plugin provides an on-demand and memory-efficient solution for handling image resizing in WinterCMS. It returns a stable URL immediately, and renders missing resized assets on first request (with a hard concurrency cap) to avoid server exhaustion.

Under the hood, the image pipeline uses League\Glide (v3) for storage-backed images (Flysystem disks), with a fallback to Intervention Image for remote URLs and PDFs.

Features

Summary	Category	Feature	Benefit
Performance	On-Demand Rendering	User does not wait for image creation; the first request triggers rendering.	Instant URL output on the frontend.
Optimization	Local Disk Path Handling	Avoids unnecessary memory consumption by reading file paths instead of entire file content into PHP.	Lower RAM overhead per process.
Resilience	Memory-Efficient PDF Handling	Optimizes ImageMagick to process PDFs at low DPI and only the first page.	Prevents memory leaks and crashes.
Control	CLI Tools (warmup, clear, prune)	Provides complete cache and maintenance control via the command line.	Automated maintenance workflows.
Stability	Concurrency Control	Uses a semaphore lock to cap simultaneous resize jobs.	Protects server CPU/RAM from overload.

1. Installation and Configuration (.env)

The plugin uses a dedicated configuration file (config.php) which pulls its values from your main .env file. You should place these variables in your environment file to easily manage your setup across different deployments (staging, production).

.env Variables

Variable	Default Value	Description	Used In
IMAGE_RESIZE_DRIVER	gd	The Intervention Image driver to use: gd or imagick.	ImageResizer.php
IMAGE_RESIZE_DISK	local	The default storage disk for reading source files and writing cache files.	All components
IMAGE_RESIZE_JPG_QUALITY	82	Default JPEG output quality (0-100).	ImageResizer.php
IMAGE_RESIZE_WEBP_QUALITY	80	Default WebP output quality (0-100).	ImageResizer.php
IMAGE_RESIZE_AVIF_QUALITY	50	Default AVIF output quality (0-100).	ImageResizer.php
IMAGE_RESIZE_QUALITY	80	Backward-compatible fallback output quality (0-100).	ImageResizer.php
IMAGE_RESIZE_DISABLE_AVIF	false	If true, never generate AVIF ("best" falls back to WebP/JPEG).	ImageResizer.php
IMAGE_RESIZE_CONCURRENCY	3	(Critical) Max simultaneous sync resize operations across requests.	/mresize/{hash}
IMAGE_RESIZE_LOCK_WAIT	60	Seconds a request waits for a free concurrency slot.	/mresize/{hash}
IMAGE_RESIZE_LOCK_POLL_US	200000	Poll interval (microseconds) while waiting for a slot.	/mresize/{hash}

Runtime

No queue worker is required. Missing resized assets are rendered synchronously on first request, with a strict concurrency limit.

2. Twig Filter: qresize - Detailed Parameters

The qresize filter is the primary tool for using the plugin in your templates. It instantly returns a URL, deferring the actual work to the background.

Twig Syntax

{{ image.path | qresize(width, height, options) }}

Parameters

Parameter	Type	Required	Description	Example
src	string	Yes	The source path to the original image file.	image.path
width	int/null	No	Desired output width. Required if height is null.	400
height	int/null	No	Desired output height. Required if width is null.	300
options	array	No	Key/value pairs to control the resizing process.	{'mode': 'crop', 'quality': 90}

Options Array Keys (opts)

Key	Type	Description	Default
mode	string	Resizing mode: auto, crop, or fit.	'auto'
quality	int	Output quality for JPEG/WebP (0-100).	80
format	string	jpg, webp, avif, png, gif, best (prefers AVIF, then WebP, then JPEG based on client + server support), or best_existing (uses cached AVIF if it already exists; otherwise falls back to WebP/JPEG).	'best'
disk	string	Overrides the default disk for this specific request.	'local'

3. PHP Block Functionality: mresize_path()

This function is registered to allow developers to pre-register resize requests for a directory directly from custom PHP code (e.g., in a component's onStart() method or a CMS page's code block). The resized assets will still be rendered on first request.

Function Call Syntax

mresize_path($path, $w, $h, $opts = [], $recursive = false);

Function Parameters

Parameter	Type	Required	Description
$path	string	Yes	Path to a directory or file. Resolves to parent folder if a file.
$w	int/null	No	The desired output width in pixels.
$h	int/null	No	The desired output height in pixels.
$opts	array	No	Array of options (mode, quality, etc.) passed to the job.
$recursive	bool	No	Set to true to scan subdirectories within the resolved path.
$opts['disk']	string	No	Overrides the default disk to use for this batch job.

Backward compatibility: older calls that passed $disk as a 6th argument still work, but the preferred way is using $opts['disk'].

Example Usage in a Component:

function onStart()
{
    // When the component initializes, it queues all images in 'media/user-uploads' 
    // to be resized to 1024px wide.
    $jobsQueued = mresize_path(
        'user-uploads/latest-image.jpg', // Path resolves to the 'user-uploads' directory
        1024,
        null, 
        ['quality' => 85, 'format' => 'webp', 'disk' => 'media'],
        true // Recursive
    );
}

4. Command Line Interface (CLI) - All Parameters

A. mresize:warmup (Batch Processing)

Recursively generates resized images for a directory.

Parameter	Alias	Required	Description	Example Value
path	(arg)	Yes	Relative folder path to scan (inside storage/app/media).	"media/gallery"
--width		No	Target width(s) (comma-separated).	400,800
--height		No	Target height(s) (comma-separated).	200
--format		No	Output formats (comma-separated).	jpg,webp
--recursive	-r	No	Scans subdirectories within the specified path.	(flag only)
--force	-f	No	Forces regeneration even if cache is valid.	(flag only)
--disk		No	The specific storage disk to operate on.	uploads
--mode		No	Resize mode (auto, crop, fit).	crop
--quality		No	Output quality (0-100).	90

Example Usage:

php -d memory_limit=1024M artisan mresize:warmup "media/gallery" --width=400,800 --format=jpg,webp --recursive --force

B. mresize:clear (Cache Cleanup)

Removes resized images based on filter criteria.

Parameter	Required	Description	Example Value
--disk	No	The storage disk to clear the cache from.	local
--width	No	Clear only images matching this target width.	400
--height	No	Clear only images matching this target height.	300
--path	No	Filter by segment of the original source file path.	products/banners
--dry-run	No	Displays matching files without deleting them.	(flag only)

C. mresize:prune (Orphan Removal)

Removes cached resized images where the original source file no longer exists.

Parameter	Required	Description	Example Value
--disk	No	The storage disk to prune the cache on.	media
--dry-run	No	Displays which orphans would be deleted.	(flag only)

Example Usage:

# Delete all orphan files on the default disk
php artisan mresize:prune

Backward compatibility: the PHP function name queuedresize_path() is still registered as an alias.