Product Image Upscaler

Configuration manual: Product Image Upscaler

Requirements

• Shopware 6.7
• PHP extension GD (required). Imagick is optional and recommended, as it produces sharper edges.
• A running message queue worker. New uploads and queued jobs are processed in the background.

You'll find the configuration under Extensions → My extensions → Product Image Upscaler → Configure. All settings apply shop-wide. Selecting a sales channel has no effect.

Recommended first steps

1. Under Target size, check the Minimum edge. The default of 500 px meets the Google Shopping requirement.
2. Save.
3. In the Process existing images card, click "Upscale all product images". Keep the browser window open while it runs.
4. From now on, product images are processed automatically when they're assigned to a product.

The original images are never changed. The plugin creates copies and only switches the product assignment to the larger version.

The settings in detail

Process existing images

Shows the current state: images that are still too small, images already processed, the active method. Depending on the situation, it offers the matching actions:

• Upscale all product images – Processes all undersized product images in blocks. The run can be cancelled at any time.
• Add to queue – As above, but in the background via the worker. The window doesn't need to stay open.
• Refresh to new minimum edge – Appears after you've raised the minimum edge. Re-renders the affected copies from the unchanged original.
• Re-link existing images – Links copies that already exist back to the products, without recalculating them.
• Revert – Switches the products back to the originals. The copies are kept.
• Reset orphaned images – For special cases, such as after a database migration: copies without a stored mapping are matched to their original by file name. Use "Show preview" first to see what will happen.

Image source

Use original images as product images (default: off)
On save, switches every product back to its original image. Nothing is deleted: clear the checkbox and the copies are linked again. While it's set, the plugin leaves new uploads alone.

Target size

Minimum edge in pixels (default: 500)
Images are enlarged so that the shorter edge reaches this value. The aspect ratio is kept: 400 × 365 becomes 548 × 500, not 500 × 500.

Maximum scale factor (default: 4.0)
Images that would need a stronger enlargement are skipped and logged. This prevents visible quality loss.

Maximum aspect ratio (default: 3.0, i.e. 3:1)
Skips very long or narrow images, such as dimension drawings or strips showing the package contents. They're assigned to a product, but they aren't product photos.

Image processing

Method (default: Automatic)
"Automatic" picks the best available method: Imagick if installed, otherwise GD. You'll only need "Force ImageMagick" or "Force GD" in exceptional cases.

Sharpening amount (default: 0.35)
From 0.0 (off) to 1.0 (maximum). With heavily compressed source images, high values also accentuate JPEG artefacts.

JPEG quality (default: 90) and WebP quality (default: 90)
From 1 to 100, applies only to the generated copies. For product images, 85 to 92 works well.

Automation

Process newly uploaded product images automatically (default: on)
Undersized images are queued when they're assigned to a product. The upload itself doesn't get any slower.

Stop processing

"Stop processing and cancel queue" blocks new jobs and removes the pending jobs of this plugin. Other Shopware jobs aren't affected. An image that's currently being processed is still finished safely. Keep the page open until the success message appears. Images and product assignments aren't changed.

"Enable processing again" lifts the block. Discarded jobs don't come back; queue them again if needed.

Deactivating and uninstalling

• Deactivating and uninstalling don't change any product images. Products showing an upscaled copy keep it.
• If the products should show the originals again, first enable "Use original images as product images" under Image source, and wait until all assignments have been switched.
• Before deactivating, use "Stop processing" so that no jobs of this plugin are left in the queue.
• Uninstalling with "Delete all data" removes the mapping table, the plugin settings, the media tag webla-upscaled and the plugin's media folders. The copies move to the parent folder and stay in use as product images. The originals are then no longer assigned to any product and count as unused for media:delete-unused.

User permissions

• View status – read products, read media
• Upscale – edit products, create media
• Revert – edit products
• Refresh, delete copies – additionally delete media

Console commands

For large catalogues or automation via cron job:

• bin/console webla:upscale:scan – Shows which product images are too small and changes nothing. --details lists every image, --min-edge= checks a different value.
• bin/console webla:upscale:run – Upscales undersized images, via the queue by default. --sync processes immediately, --limit= limits the number, --dry-run only shows what would happen, --refresh refreshes copies below the current minimum edge, --media-id= processes individual images.
• bin/console webla:upscale:status – Shows the current state.
• bin/console webla:upscale:revert – Switches all products back to the originals. --limit= for a trial run, --delete also deletes the copies (asks for confirmation; --force skips it).
• bin/console webla:upscale:processing [status|stop|resume] – Shows, stops or resumes processing without deleting images.
• bin/console webla:upscale:repair-orphans – Resets orphaned copies. --dry-run only shows what would happen, --queue processes via the queue.

Log

The plugin writes to its own log file: var/log/webla_image_upscaler_.log. In production, only warnings and errors are logged, for example skipped images. Per-image success messages only appear in the development environment.