Installation




Before installing the extension, please make sure to Backup your web directory and store database


You will require to install MageDelight Base Extension first. If it is not installed then please download it from https://www.magedelight.com/pub/extensions/magedelight-base.zip and unzip the package file into the root folder of your Magento 2 installation.

Root Directory is - "app/code/magedelight/#YourExtensionName#"

  • Unzip the extension package file into the root folder of your Magento 2 installation.
  • Connect to SSH console of your server:
    • Navigate to the root folder of your Magento 2 setup
    • Run command as per below sequence,

      php bin/magento setup:upgrade

      php bin/magento setup:di:compile

      php bin/magento setup:static-content:deploy

      php bin/magento cache:clean

  • log out from the backend and log in again


If you are using Magento 2.3 or later then you do not need to activate license. Extension will be activated with silent activation mechanism and does not require activation keys to be entered manually.   



Backend Configuration (Admin side)



FieldDescription
EnableThis option allows you to activate or deactivate the Image Cleanup extension for the selected
website scope.
• Set “Yes” to enable all features of the module, including image detection, trash system, and
cleanup operations.
• Set “No” to temporarily disable the extension without uninstalling it.

Disabling the module stops all automated CRON scans and cleanup processes.
Image Trash Folder PathDefines the storage path where unused images will be safely moved when sent to the trash
instead of being deleted permanently.
By default, the folder path is:  var/trash/imagecleanup This path is inside the Magento
media directory
, ensuring that images remain accessible for restore operations. You can customize
the folder name if required (for example, var/trash/media_cleanup).

Always make sure the specified directory has read/write permissions for Magento’s file system user.

FieldDescription
Auto CleanupEnables or disables automatic image cleanup via CRON.
When set to “Yes”, the extension automatically performs cleanup actions (move or delete) based on the configured schedule. 
Clean up ActionDefines what the automated cleanup should do with the detected unused images.

Available options:
Move to Trash – Automatically transfers all unused images to the trash folder for safe review before deletion.
Delete Permanently – Automatically deletes unused images from the system and trash folder with no restore option.

Use “Move to Trash” for safer operation and “Delete Permanently” for aggressive cleanup.
Clean up FrequencyDetermines how often the automatic cleanup job runs through CRON.

Available values:
Daily – Runs every day at the set time.
Weekly – Runs once a week.
Monthly – Runs once a month.

Choose a frequency that aligns with your store’s image update rate and maintenance policy.
Clean up TimeSets the exact time (HH:MM: SS) for the CRON job to start the cleanup operation.
Example: 02:00:00 will execute cleanup daily/weekly/monthly at 2 AM.
It is recommended to schedule cleanup during low-traffic hours to avoid performance impact on your live store.

The cleanup process automatically handles the removal of the unused images identified during the scan.

  • Functionality: A dedicated cron job moves unused images either to the Trash folder or Deletes them Permanently, based on the Cleanup Action configured in the extension's settings.
  • Configuration:
    • Once Auto Cleanup is enabled, images will be automatically moved to trash or permanently deleted from the trash.
    • Set the Cron Frequency and Cleanup time to run after the Auto Scanning cron has completed its task.

⚠️ Important for Permanent Deletion: For images to be permanently deleted, they must not be present in the Restore & Delete Permanently grid. This acts as a final safeguard.
⚠️ Important for Move to Trash: For images to be moved to trash, they must be scanned First in the Unused Image grid.

FieldDescription
Auto Scan Enable

Enables or disables the automatic image scanning process through CRON.When set to “Yes”, Magento will

automatically run the scan process for images at the defined frequency and time.

This ensures your image database remains up to date without requiring manual initiation of the scan.

Auto Scanning / Refresh

Allows you to choose the specific types of scans that should be performed automatically.

Available options:

Product Scan – Scans all product images to identify unused or missing files.

CMS Scan – Scans CMS pages and blocks for unused or broken image references

.• Category Scan – Scans category-level images for detection and verification.

Multiple options can be selected to perform combined scanning operations in a single CRON cycle.

Scan Frequency

Defines how often the automatic image scanning process runs via CRON.

Available values:

Daily – Runs every day.

Weekly – Runs once a week.

Monthly – Runs once a month.

Select a frequency based on your media update rate and business maintenance policy.

Scan Time

Specifies the exact time (HH:MM:SS) at which the automatic scan should begin.

Example: 01:30:00 will start scanning every day/week/month at 1:30 AM.

It is recommended to set scanning during off-peak hours to minimize performance impact on live customers.

This process identifies and lists unused images on your store.

Command Line Interface (CLI): You can trigger a scan manually using the following command, specifying the image type:
Bash : php bin/magento magedelight:imagecleanup:scan

    • Options: Use the -t or --type option to specify the target images:
      • --type[=TYPE] : Type of images to scan (e.g., product, cms, missing, or all).
      • Default: "all"
  • Cron Job (Auto Scanning): For continuous, automated monitoring, set up the cron job:
    • Navigate to Configuration > Magedelight > Image Cleanup > Auto Image Scanning.
    • Enable auto scanning, select the desired image types for the scan, and configure the Cron Frequency and time.

⚠️ Important: Ensure all unused images are scanned and correctly listed in the grid before initiating the cleanup/move to trash operation.

FieldDescription
Email Notifications

Enables or disables the email notification system for the Image Cleanup extension.

When set to “Yes”, the system automatically sends an email update after every scheduled

cleanup job (based on CRON execution).

These emails summarise operation results — including the number of images moved,

deleted, or any issues detected during the process.

Notification Email Address(es)

Specify one or more recipient email addresses to receive cleanup notifications.

Use a comma (, ) separator to add multiple addresses (e.g., [email protected],

[email protected]).

Ensure the listed email addresses belong to team members responsible for monitoring store

maintenance or DevOps activities.

Email Template for Success

Selects which email template to use when a scheduled cleanup completes successfully.

Default Template: Image Cleanup Success (Default) This email includes details such as:

• Date/time of cleanup

• Total images processed

• Space saved

• Next scheduled run time

Email Template for Failure

Defines the template used when a cleanup job fails due to an error or incomplete process.

Default Template: Image Cleanup Failure (Default)

This alert helps administrators quickly identify and resolve CRON or permission issues that

prevent cleanup completion.

Recommended for proactive system monitoring and maintenance tracking.

FieldDescription
Set Batch Size

Defines the number of images processed in a single batch during scan or cleanup

operations.

Example: If set to 100, the extension will process 100 images per cycle before proceeding to

the next batch.

Adjust this value based on your server’s capacity and media directory size — lower for

limited resources, higher for powerful servers.

Enable Logs

Enables or disables the logging system for all image cleanup activities.

When set to “Yes”, detailed logs are stored in:

var/log/magedelight/md_imagecleanup.log

Each log entry contains the image name, path, admin username, action (deleted/moved),

and date/time of the operation.

These logs help administrators track actions and audit cleanup history for troubleshooting or verification.

Enable CRON for Logs Auto Cleaning

If enabled, the system will automatically clear old log entries based on the defined

retention period.

This prevents log files from becoming excessively large and consuming unnecessary disk space.

Auto-Delete Logs Older than Days

Defines the retention period (in days) for log records.

Example: If set to 7, logs older than 7 days will be deleted automatically.

Helps maintain optimal performance and ensures only recent logs are retained.

CRON Frequency

Sets how often the log auto-cleaning CRON job will execute.

Available values:

Daily – Runs every day.

Weekly – Runs once a week.

Monthly – Runs once a month.

Recommended: Daily to keep logs lean and current.

CRON Time

Specifies the time of day (HH:MM:SS) when the CRON job for log auto-cleaning should

run.

Example: 02:00:00 runs at 2 AM daily.

Schedule during off-peak hours to minimize server load impact.

Backend Functionality



Image Cleanup Dashboard

  • The Image Cleanup Dashboard provides a centralized overview of your store’s image optimization activities.
  • It displays real-time statistics on unused images, trash operations, restored files, deleted files, and scheduled cleanup jobs.
  • This helps administrators track the effectiveness of image maintenance tasks, assess potential space savings, and monitor automation via CRON schedules.
  • Path:   Magedelight → Image Cleanup → Dashboard
Section / FieldDescription
Total Unused Images

Displays the total count and size of all unused images detected across Product, CMS, and

Category sections.

Example: 682 (61.89 MB) shows there are 682 unused images totaling 61.89 MB.

Images in Trash

Shows the number and total size of images currently stored in the trash folder.

This indicates files awaiting review before permanent deletion.

Images Restored

Displays the count of images that were restored from trash back to their original locations.

Useful for tracking accidental deletions or verified image recoveries.

Images Deleted

Indicates how many images have been permanently deleted from the system after review

or CRON cleanup.

Space Reclaimed

Shows the total storage space that has been freed after permanently deleting unused

images.

This metric helps in assessing hosting and storage optimization.

Potential Space Savings

Estimates how much space can be reclaimed if all currently unused images are deleted.

This helps in planning cleanup actions and capacity management.

Moved to Trash Details

Provides a breakdown of how many images from each module (Product, CMS, Category)

have been moved to trash.

Gives clarity on where most unused images originate.

Permanently Deleted Details

Lists the number of images permanently deleted per module type — Product, CMS, and

Category — along with total reclaimed space per category.

Monthly Image Restoration Trends

Displays a visual bar chart showing the number of images restored month-wise.

This helps you analyze restore activities and recovery trends over time.

Scheduled Jobs Status

Lists all configured CRON jobs related to image cleanup, including job name, enable status,

CRON state, and timestamps for creation, scheduling, and execution.

If no jobs appear, it means automatic cleanup or scanning has not been configured yet.

Usage Tip: Regularly review the Dashboard to evaluate cleanup effectiveness, space utilization trends, and ensure CRON-based automations (for scan and cleanup) are running successfully.

Cleanup Management

Product Images Cleanup

  • The Product Images Cleanup section allows administrators to scan, review, and manage unused product images stored in the Magento media directory.
  • This tool helps you identify images that are no longer associated with any catalog products and safely move them to trash or delete them permanently.
  • It provides real-time scan progress, a batch-based processing log, and a grid view listing all unused images for quick review and action.
  • Path: Magedelight → Image Cleanup → Cleanup Management → Product Images

Section / FieldDescription
Start Scan

Begins the image scanning process for product images.

When clicked, the system starts analyzing the media directory to identify images that are

not associated with any products in the catalog.

Note: Do not close the window until the scan is complete, as it runs in the active browser session.

Move All to Trash

Moves all unused product images found during the scan to the Trash Folder instead of

deleting them immediately.

This provides a safe intermediate step, allowing you to review or restore images later from

the Trash before permanent removal.

Delete All Images

Permanently deletes all unused product images detected during the scan.

Use this option only after reviewing the scan results, as the images removed by this action

cannot be recovered unless backed up.

Image Scan Progress – Product

Displays real-time progress of the ongoing product image scan.

It includes batch count, number of processed images,

and number of unused images detected.

Each operation’s details appear in the Processing Log, helping you track performance and

progress.

Scan Mode (Foreground)

Indicates the scan is running in foreground mode, meaning it is actively processed within

the browser session.

Background mode (if available) would run asynchronously via CRON jobs.

Current Batch

Displays the batch number currently being processed.

Batch processing ensures that the scan runs efficiently, handling a manageable number of

images at a time based on the configured batch size.

Images Processed

Shows the total number of images that have been scanned so far, including both used and

unused images.

Unused Images Found

Indicates how many images are not linked to any product, category, or CMS reference.

These are candidates for cleanup or trashing.

Processing Log

Provides a live status feed of scan progress.

Each entry shows:

• Batch number processed

• Number of images scanned

• Number of unused images found

• Final completion summary

This helps administrators confirm that all batches were scanned successfully.

Grid View (Results Table)

Displays the detailed list of all unused images found.

Each row contains the following details:

Image – Thumbnail preview of the unused image.

Path – File path in the Magento media directory

.• Size – File size in KB or MB.

Image Type – File format (JPG, PNG, etc.).

Created At – Timestamp of when the image was originally uploaded.

Action – Dropdown menu to perform individual operations such as Move to Trash, Delete

Permanently, or View in Folder.

Filters & Columns

Use these controls to filter unused images by size, type, or creation date, and customize

visible columns in the grid. This helps in reviewing only relevant items before performing

bulk operations.


Usage Tip: Perform a manual scan first and review the grid before enabling Auto Image Cleanup (CRON). This helps validate that the extension correctly identifies unused media in your specific store setup.

CMS Image Cleanup

  • The CMS Image Cleanup section helps administrators identify and manage unused images associated with CMS Pages and CMS Blocks.
  • It scans the media directory to locate images that are uploaded but not linked to any CMS content, allowing you to safely move them to trash or permanently delete them.
  • This ensures your CMS media library remains clean, lightweight, and well-organized — improving both storage efficiency and site performance.
  • Path:Magedelight →  Image Cleanup → Cleanup Management → CMS Images

Section / FieldDescription
Start Scan

Initiates the CMS image scanning process to detect unused files. The scan reviews

CMS Pages and Blocks for any unreferenced images.

Move All to Trash

Moves all unused CMS images found during the scan into the trash folder. This

option allows a safe rollback if needed before deletion.

Delete All Images

Permanently deletes all detected unused CMS images from the media directory.

Use with caution, as deleted files cannot be restored.

Image Scan Progress – CMS

Displays real-time progress including batch number, total images scanned, and

unused images found.

Processing Log

Shows live scanning activity, including number of images processed per batch,

unused images detected, and final completion status.

Grid View (Results Table)

Lists all unused CMS images with details such as image name, path, size, type,

creation date, and available actions (Move to Trash, Delete Permanently, etc.).

Filters & Columns

Use to filter results by size, type, or date, and customize visible columns for

efficient review and management.


Usage Tip: Perform CMS cleanup regularly (e.g., monthly) to prevent the accumulation of outdated banner or content images. This improves backup performance and reduces hosting costs.

Category Image Cleanup

  • Scans and lists unused category images with live counts and logs.
  • From the grid, you can Start Scan, then Move to Trash / Restore / Delete selected images using filters and per-row actions.
  • Path: Magedelight → Image Cleanup → Cleanup Management → Category ImageCategory Image Cleanup


Field / SectionDescription
Page Title: Category Image Cleanup

Indicates the current module section being used — specifically for cleaning up unused

category images in Magento.

Action Buttons

Move All To Trash, Delete All Images, and Start Scan — primary controls to manage

detected images. “Start Scan” initiates a new scan for unused images.

Warning Message

A yellow alert box reminding the admin not to close the window until the scan process

completes.

Info Message

A blue information note explaining that this section shows images uploaded to the

directory but not assigned to any category pages.

Image Scan Progress (Category)

Displays the scan summary for the current run, including batch count, number of

images processed, and unused images found.

Current BatchDisplays the current batch number being processed (e.g., Batch 1).
Images ProcessedTotal number of images scanned during the current operation (e.g., 23).
Unused Images FoundNumber of images detected as unused (e.g., 23).
Processing Log

A real-time log panel displaying each step of the scan — initialization, data

loading, processing results, and completion messages. Logs appear in green

text with timestamps for transparency and debugging.

Actions DropdownAllows bulk operations (e.g., move selected images to trash or delete).
Grid/Table Section

Displays the list of identified unused images with detailed information for

each entry.

ImageThumbnail preview of the unused image file.
Image NameThe file name of the image (e.g., 813MIZWXKL.jpg).
Path

Directory path of the image within Magento’s media folder

(e.g., catalog/category/chocolate/813MIZWXKL.jpg).

SizeFile size of the image (e.g., 367.439 KB).
Extension TypeImage file format (e.g., JPG).
Created At

Timestamp showing when the image was uploaded or created in the

system.

Action (per record)

Dropdown menu with options like Move to Trash, Restore, or Delete

for individual image management.

Filters / Columns / Default View

Toolbar controls allowing admins to filter results, customize visible

columns, or reset to the default grid layout.

Pagination Controls

Allows navigation between multiple pages of scan results

(e.g., “2 per page”, “1 of 12”).

Run the scan during low-traffic hours to avoid performance impact. Always review images in the trash before permanent deletion to ensure no important category assets are removed.

Missing Images


Product Missing Images

  • Scans and lists missing image references on products (by name and SKU).
  • Use the grid to review affected items and upload the missing images directly from the Action column.
  • Path: Magedelight → Missing Images → Missing Product Images → Product Missing Images


Field Description
Page TitleSection to detect and list missing product images across the catalog.
Start Scan

Triggers a scan to find product image references that are absent from

the media directory.

Info Note

Explains that listed items are referenced on products but not present

in /pub/media/catalog/product.

Current BatchBatch number currently being processed.
Total ProcessedNumber of product image references scanned.
Missing Images FoundCount of missing product images detected.
Processing Log

Real-time log of scan initialization, progress, and completion

(with timestamps).

Grid/Table SectionResults list for review and action.
IDRecord index.
Missing PathExpected media path of the missing product image.
Image NameFilename of the missing image.
SourceProduct where the image is referenced (Product name and SKU).
Detected AtTimestamp when the missing reference was identified.
Action (Upload Image)Quick link to re-upload the missing image for that product.
Filters / Columns / PaginationTools to filter results, choose visible columns, and navigate pages.

Run this after product imports/migrations to catch broken media. After uploading, flush cache/CDN and re-scan to confirm the product images render correctly on the storefront.

CMS Missing Images

  • Scans and lists missing image references within CMS Pages and Blocks.
  • Admins can review missing paths, identify affected sources, and upload the missing images directly from the grid.
  • Path: Magedelight → Missing Images → Missing CMS Images → CMS Missing Images


Field / SectionDescription
Page TitleDisplays the section for detecting missing CMS images across pages and blocks.
Action Button (Start Scan)

Initiates the scan to detect missing or deleted images referenced in CMS pages or

blocks.

Information Note

Explains that this section lists image paths that are referenced but not available in

the media directory.

Current BatchIndicates the current batch number of the scan process.
Total ProcessedShows the total number of CMS image paths scanned.
Missing Images FoundDisplays how many CMS image paths were found missing.
Processing Log

Real-time log panel showing scan initialization, progress, and completion

messages with timestamps.

Grid/Table SectionDisplays the list of detected missing CMS images for admin review.
IDSerial number of each missing image record.
Missing PathShows the missing file path in the media directory.
Image NameDisplays the name of the missing image file.
Source

Indicates where the missing image is referenced (e.g., CMS Page or

Block ID).

Source TypeSpecifies whether the source is a CMS Page or CMS Block.
Detected AtTimestamp of when the missing image reference was identified.
Action (Upload Image)

Provides a quick action link to re-upload the missing image directly

from the grid.

Filters / Columns / Pagination

Allows filtering, customizing columns, and navigating through

multiple pages of results.

Run this scan periodically to ensure CMS pages and blocks are free from broken image links, improving both user experience and store presentation quality.

Category Missing Images

  • Scans and lists missing image references in product categories.
  • Admins can review the affected categories and upload the missing images directly from the grid to restore visuals.
  • Path: Magedelight → Missing Images → Missing Category Images → Category Missing Images


Field / SectionDescription
Path

Magedelight → Missing Images → Missing Category Images →

Category Missing Images

Page Title

Section used to detect and list missing category images across the Magento

store.

Start Scan

Initiates the scan to identify category image references that are missing from

the media directory.

Info Note

Explains that this section lists images referenced in categories but not available

in /pub/media/catalog/category.

Current BatchShows the current batch being scanned.
Total ProcessedDisplays the total number of category image references scanned.
Missing Images FoundIndicates the number of missing category images detected.
Processing Log

Shows real-time progress messages, including initialization, processing, and

completion details.

Grid/Table Section

Displays the list of detected missing category images with details for review

and action.

IDSerial number for each missing image entry.
Missing PathThe expected directory path of the missing image file.
Image NameThe file name of the missing category image.
Source

Indicates which category the missing image belongs to

(e.g., Default Category, Fitness Equipment).

Detected AtTimestamp showing when the missing image was identified.
Action (Upload Image)Allows quick upload of the missing image directly from the grid.
Filters / Columns / PaginationOptions to filter results, adjust column visibility, and navigate through pages.

Run this scan after catalog imports or media cleanups to ensure all category thumbnails and banner images display correctly on the storefront.

Demo


Click here to visit the frontend.

Click here to visit the backend admin panel.

FAQs


Click here to visit FAQs.

Support


Click here to raise a support ticket using your MageDelight account.

Additional Services


Click here to get the customized solution for this extension.



Thank you for choosing MageDelight!



  • No labels