> For the complete documentation index, see [llms.txt](https://docs.momocode.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.momocode.de/en/shopware-6/media-cleanup-dashboard/2.-installation.md). # 2. Installation ## Install the Plugin 1. Download the plugin from the Shopware Store or as a ZIP file. 2. In the Shopware Administration, navigate to **Extensions → My Extensions**. 3. Click **Upload extension** (for ZIP installation) or find the plugin in the list. 4. Click **Install** and then **Activate**. 5. No database migration is required — the plugin does not create any custom tables. ## Getting Started 1. Navigate to **Content → Media Cleanup** in the Administration. 2. Click **Start scan** to begin the analysis. The scan runs in the background in small batches — while it is running, the dashboard shows its progress (e.g. "1,250 media checked") and the number of unused media found so far. You can wait for the results or leave the page and return later (see [Background Processing](#background-processing-of-the-scan)). 3. Once the scan is complete, the list of unused media files appears. Results remain valid for 4 hours — page navigation and delete operations do not trigger a full re-scan. 4. Use the filters (file type, minimum size, age) to narrow down the results. 5. Select individual files via checkbox or click **Select all**. 6. Click **Delete selected** — a confirmation dialog appears showing the count and total size. 7. Confirm the deletion. The result (deleted / skipped / failed) will be displayed. 8. To refresh results, click **Rescan**. ## Background Processing of the Scan The scan is executed in the background via Shopware's message queue (Symfony Messenger) and split into small batches. This keeps it clear of PHP and proxy timeouts — even for large media libraries. * **Default setup:** Shopware routes the scan to the asynchronous Doctrine transport (`MESSENGER_TRANSPORT_DSN=doctrine://default`). The **Admin Worker**, enabled by default, processes the queue as long as the Administration is open in a browser tab. No additional setup is required — thanks to batching, the scan completes with the Admin Worker alone. * **Recommended for large media libraries:** For reliable background processing — regardless of whether the Administration is open — set up a CLI worker, e.g. via Supervisor or systemd: ```bash bin/console messenger:consume async low_priority ``` Once a CLI worker is running permanently, you can optionally disable the Admin Worker. * **Synchronous transport:** If `MESSENGER_TRANSPORT_DSN=sync://` is configured, the scan runs synchronously within the request that starts it. For very large media libraries, PHP or proxy timeouts may occur — use the asynchronous transport in that case. **What you see during the scan:** * **Progress:** The dashboard shows how many media have been checked and how many unused media have been found so far. The display updates automatically. * **Missing worker hint:** If the scan remains queued for more than 2 minutes, a hint appears indicating that no worker seems to be processing the message queue. Keep the Administration open (Admin Worker) or set up a CLI worker. * **Stopped without progress:** If the scan makes no progress for 10 minutes (e.g. because all Administration tabs were closed and no CLI worker is running), it is stopped with an error message. Click **Retry** to start the scan again. ## Setting Up User Permissions The plugin adds two ACL privileges. To grant access to staff members: 1. Navigate to **Settings → System → Users & Permissions → Roles**. 2. Select the desired role (or create a new one). 3. Find **Media Cleanup** in the permissions section. 4. Assign the required privilege(s): * **Read** — access to the dashboard and the unused media list * **Delete** — permission to delete unused media files 5. Save the role. ## Notes * Compatible with Shopware 6.6.x and 6.7.x (PHP 8.2+). Version 2.x supports Shopware 6.7, version 1.x supports Shopware 6.6. * The plugin communicates only with your own Shopware instance — no external services. * By default, the scan runs in the background via the Admin Worker. For large media libraries, we recommend a CLI worker (see [Background Processing](#background-processing-of-the-scan)). * Deleted files cannot be recovered. Please review your selection carefully before confirming. * For very large media libraries, consider using the filters to process deletions in smaller batches. * **Detection is based on Shopware's native logic:** The plugin uses Shopware's built-in unused media detection — the same logic that powers the `media:delete-unused` CLI command. The plugin is not responsible if Shopware classifies a file as unused that is still in use. Always review your selection carefully before deleting. ## Support If you have questions or issues, please use the Shopware support tool or contact us at .