How-To Guide¶

This guide provides step-by-step workflows for common tasks with Media Booster.

How the Plugin Works¶

Data Flow Overview¶

Media Booster processes images in three independent steps:

[Media Library] → [Media Booster Queue] → [Processed Images]
      ↓                   ↓                      ↓
  Original JPG        Background             WebP version +
  PNG files           processing             optimized metadata

Processing Flow: 1. You start processing manually or the plugin starts automatically (depending on configuration) 2. Media Booster fetches unprocessed images from the media library 3. Each image is processed in a batch 4. Progress is displayed in the dashboard 5. After completion, statistics are updated

Common Workflows¶

How to: Initial Plugin Setup¶

Goal: Optimally configure Media Booster after installation

Prerequisites: - Plugin is installed and activated - Access to Shopware Administration

Steps:

Check server compatibility
Navigate to: Settings → Extensions → Media Booster
Check the "Server Information" section
Note which features are available (Imagick, WebP, AVIF)
Open plugin settings
Navigate to: Settings → Extensions → Media Booster
Alternatively: Click "Plugin Settings" in the dashboard
Configure basic settings
Batch Size: 50 (default value, adjust if needed)
Automatic Processing: "Manual only" for the beginning
Enable conversion (recommended)
Conversion Mode: Select "WebP"
Image Quality: 80
Thumbnail Quality: 60
Enable SEO optimization (optional)
Alt Tag Mode: "Optimize Alt Tags"
Update Mode: "Only fill empty"
Save settings
Click "Save"
Start first processing
Navigate to: Settings → Extensions → Media Booster
Click "Start All"
Monitor the progress

Result: The plugin is configured and begins image optimization.

How to: Convert Existing Images to WebP¶

Goal: Convert all existing images in the media library to WebP

Prerequisites: - WebP is supported by the server (check in dashboard)

Steps:

Adjust settings
Navigate to: Settings → Extensions → Media Booster
Conversion Mode: Select "WebP"
Image Quality: 80 (or as needed)
Save
Start conversion
Navigate to: Settings → Extensions → Media Booster
Click "Convert"
Monitor progress
The page refreshes automatically
Wait until the progress bar reaches 100%
Verify result
Open your shop in a browser
Open developer tools (F12)
Check in the Network tab that images are loading as WebP

Result: All suitable images now have WebP versions that are automatically delivered.

Note: Original images remain and serve as fallback for older browsers.

How to: Save Storage Space Through Image Resizing¶

Goal: Reduce oversized original images to reasonable dimensions

Prerequisites: - Imagick is installed on the server - Important: Backup of media files created!

Steps:

Create backup
Back up the /public/media/ directory on your server
This is important as original images will be overwritten!
Configure settings
Navigate to: Settings → Extensions → Media Booster
"Enable Image Resize": On
Maximum Width: 2000 (or as needed)
Maximum Height: 2000 (or as needed)
Resize Mode: "Fit within bounds"
Save
Start processing
Navigate to: Settings → Extensions → Media Booster
Click "Resize"
Verify result
Observe the "Space saved" statistic
Randomly check product images for quality

Result: All oversized images have been reduced to maximum dimensions.

Troubleshooting: If quality issues arise, restore backup and choose higher maximum dimensions.

How to: SEO Optimization for All Product Images¶

Goal: Automatically fill missing alt tags and titles with product information

Prerequisites: - Products have maintained names

Steps:

Configure SEO settings
Navigate to: Settings → Extensions → Media Booster
Alt Tag Mode: "Optimize Alt Tags"
Product Images - Update Mode: "Only fill empty" (recommended)
Product Images - Alt Template: "Product Name" or "Product Name + Shop Name"
Enable Title Optimization: On (optional)
Save
Start SEO optimization
Navigate to: Settings → Extensions → Media Booster
Click "SEO"
Verify result
Open a product image in the media library
Check that alt tag and title are set
Test in the frontend (view source code)

Result: All product images without alt tags now have meaningful alternative texts.

How to: Set Up Automatic Daily Optimization¶

Goal: New images are automatically optimized every night

Prerequisites: - Shopware Scheduled Tasks are correctly configured - Cron job runs regularly

Steps:

Enable automatic processing
Navigate to: Settings → Extensions → Media Booster
Automatic Processing: "Once daily"
Enable all other desired functions
Save
Verify cron job
Ensure the Shopware Scheduled Task Runner is running
Typical cron entry: * * * * * php /path/to/shopware/bin/console scheduled-task:run

Result: Media Booster automatically processes new images once daily.

How to: Reset Progress and Start Over¶

Goal: Process all images again (e.g., after changing quality settings)

Steps:

Open dashboard
Navigate to: Settings → Extensions → Media Booster
Reset progress
Click "Reset Progress"
Confirm the action
Start processing again
Click "Start All"

Result: All images are processed again, regardless of previous status.

Note: For WebP/AVIF conversion, existing converted files are skipped if they already exist.

Quick Reference¶

Task	Key Steps	Required Settings
Enable WebP	Conversion Mode → WebP → Save → Dashboard → Start	convertMode
Reduce image size	Enable resize → Set max dimensions → Start	resizeEnabled, resizeMaxWidth/Height
Fill alt tags	Alt Tag Mode → Optimize → Choose template → Start	seoAltMode, seoAltProductTemplate
Optimize filenames	Choose filename template → Start	seoFilenameProductTemplate
Daily automatic processing	Automatic Processing → Once daily	scheduleMode

Best Practices¶

Backup before resizing: The resize function overwrites originals. Always back up first!
WebP before AVIF: WebP has better browser support. Only use AVIF if you know your target audience uses modern browsers.
Test quality: Process a few images first and check quality before processing entire inventory.
SEO gradually: Use "Only fill empty" to not overwrite manually maintained data.
Adjust batch size: Lower values (20-30) for shared hosting, higher values (100+) for dedicated servers.
Clear cache: Clear Shopware cache and any CDN cache after processing.

Troubleshooting¶

Large images skipped during AVIF conversion¶

Symptom: Many images are marked as failed/skipped when converting to AVIF.

Cause: Your server uses the GD library instead of Imagick for AVIF conversion. GD's AVIF encoder is significantly slower (10-50x) than Imagick, so images larger than 4 megapixels are automatically skipped to prevent timeouts.

Solutions: 1. Install Imagick with AVIF support (recommended): Ask your hosting provider to install or upgrade Imagick with AVIF format support 2. Use WebP instead: WebP offers good compression and works reliably with both Imagick and GD 3. Reduce image sizes first: Use the resize function to reduce images to under 2000x2000 pixels before AVIF conversion

How to check: The dashboard's "Server Information" section shows which library is being used and displays a warning if GD is used for AVIF.

What to Avoid¶

No backups: Never start image resizing without a prior backup
Too low quality: Values below 60 can create visible artifacts
Too small dimensions: Below 1500px can affect quality on Retina displays
Overwrite all without checking: Can destroy manually maintained SEO data
Large batches on weak servers: Can lead to timeouts and aborted processing
AVIF with GD on large images: Use WebP or install Imagick for reliable AVIF conversion of large images