README

This plugin provides an asynchronous and memory-efficient solution for handling image resizing in WinterCMS. By offloading resource-intensive image processing to the Laravel Queue, it prevents synchronous page loads from becoming slow and avoids server exhaustion, making it ideal for large media libraries and high-traffic environments.

Features

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

Starting Queue Workers

The plugin is useless without a running queue worker. You should use a process manager (like Supervisor) to ensure this command runs continuously:

# Start a worker process dedicated to the 'imaging' queue
php artisan queue:work --queue=imaging --tries=3 --timeout=3600

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

Options Array Keys (opts)

These control the specific resizing job:

3. PHP Block Functionality: queuedresize_path()

This function is registered to allow developers to trigger asynchronous directory-based resizing directly from custom PHP code (e.g., in a component's onStart() method or a CMS page's code block).

The primary function is to queue resize jobs for all images within a directory when the code is executed.

Function Call Syntax

queuedresize_path($path, $w, $h, $opts = [], $recursive = false, $disk = null);

Function Parameters

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 = queuedresize_path(
        'user-uploads/latest-image.jpg', // Path is a file, but resolves to the 'user-uploads' directory
        1024,
        null, 
        ['quality' => 85, 'format' => 'webp'],
        true, // Recursive
        'media' // Uses the 'media' disk
    );
}

4. Command Line Interface (CLI) - All Parameters

The CLI commands are used for mass generation and maintenance.

A. queuedresize:warmup (Batch Processing)

Recursively generates resized images for a directory.

Example Usage (Best Practice):

# Execute with high memory and force regeneration of two sizes (400px wide, 800px wide)
php -d memory_limit=1024M artisan queuedresize:warmup "media/gallery" --width=400,800 --format=jpg,webp --recursive --force

B. queuedresize:clear(Cache Cleanup)

Removes resized images based on filter criteria.

Example Usage:

# Clear all cached images related to the 'uploads/temp' directory (Dry Run)
php artisan queuedresize:clear --path=uploads/temp --dry-run

C. queuedresize:prune (Orphan Removal)

Removes cached resized images where the original source file no longer exists (i.e., orphans).

Example Usage:

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