Sync Product Cache vs Regular Product Sync in OpenMage Image Cleaner

The regular "Sync Product" action identifies orphaned original product images in media/catalog/product by comparing filesystem contents against database references, while "Sync Product Cache" targets stale resized derivatives in media/catalog/product/cache that no longer have corresponding source files.

The OpenMage Image Cleaner module by Fabrizio Balliano provides two distinct administrative actions to help merchants reclaim disk space from unused media assets. Understanding when to use sync product cache and regular product sync actions prevents accidental deletion of active images while ensuring efficient cleanup of storage bloat.

Core Differences Between the Two Actions

Both actions populate the fb_imagecleaner_image table with files candidates for deletion, but they target different directories and use different logic to determine what constitutes an "unused" image.

Action	Target Directory	Detection Logic	Entity Type ID
Sync Product (syncproductAction)	media/catalog/product (originals)	Cross-references filesystem against product attributes and media gallery tables	Positive product type ID
Sync Product Cache (syncproductCacheAction)	media/catalog/product/cache (resized)	Reconstructs original paths from cache filenames and verifies source existence	Negative product type ID (-product_type_id)

How Regular Product Sync Works

The regular product sync action scans your original product image directory to locate files that have no database references. This process is implemented in app/code/community/Fballiano/ImageCleaner/controllers/Adminhtml/FbimagecleanerController.php at lines 66-113.

Detection Algorithm

The controller executes a multi-step validation process:

1. Attribute Scanning – Retrieves all product attributes with frontend_input='media_image' to identify which database fields store image paths
2. Placeholder Exclusion – Fetches configured placeholder images from system configuration to prevent false positives
3. Gallery Cross-Reference – Queries the media gallery table for all recorded image associations
4. Filesystem Comparison – Uses array_diff($fs_images, $db_images, $media_gallery) to isolate files present on disk but absent from all database records

Files identified as orphaned are inserted into the cleanup queue with a positive entity-type ID corresponding to the product type.

When to Run Sync Product

Execute this action when you need to locate orphaned original product images that are no longer referenced by any product attribute or media gallery entry. This typically occurs after bulk product deletions, imports gone wrong, or manual database manipulations that left filesystem artifacts behind.

How Sync Product Cache Works

The sync product cache action targets Magento's image processor outputs in media/catalog/product/cache. This logic resides in the same controller at lines 115-160.

Cache-Specific Detection Logic

Unlike the original image scan, this action works in reverse:

1. Recursive Cache Walking – Traverses the entire cache directory structure using the scandirRecursive helper method from app/code/community/Fballiano/ImageCleaner/Helper/Data.php
2. Placeholder Skipping – Automatically excludes files within /placeholder/ subdirectories
3. Source Reconstruction – Rebuilds the expected original file path by extracting the last three path segments from the cached filename
4. Existence Verification – Checks if the reconstructed original path exists in media/catalog/product

If the source image is missing, the cached derivative is flagged as unused and stored with a negative entity-type ID (-product_type_id) to distinguish it from original image records.

When to Run Sync Product Cache

Run this action after you have removed unused original product images (via the regular sync) or following product deletions. This cleans up stale cached image files that would otherwise occupy space indefinitely, as Magento does not automatically purge cache derivatives when source images disappear.

Recommended Execution Order

For optimal disk space recovery without system disruption:

1. Execute Regular Product Sync First – Identify and queue orphaned originals in media/catalog/product
2. Review and Delete – Verify the discovered files in the admin grid, then remove confirmed orphans
3. Execute Product Cache Sync – Clean up the now-unreferenced cache files in media/catalog/product/cache
4. Final Cleanup – Remove the cache entries from the queue

Running the cache sync before removing original images will yield fewer results, as the algorithm only flags cache files when their sources are already deleted.

Summary

• Regular Product Sync (syncproductAction) targets media/catalog/product to find original images with no database references, using positive entity-type IDs in the fb_imagecleaner_image table.
• Sync Product Cache (syncproductCacheAction) targets media/catalog/product/cache to find resized images missing their source files, using negative entity-type IDs.
• Always run the regular sync before the cache sync to ensure proper detection of stale cache files.
• Both actions rely on the Fballiano_ImageCleaner_Helper_Data class for filesystem operations and blacklist management.

Frequently Asked Questions

What happens if I run Sync Product Cache before Regular Product Sync?

You will likely miss many stale cache files. The syncproductCacheAction algorithm specifically checks if the original source file exists; if you haven't cleaned up orphaned originals yet, their cache derivatives will still appear "valid" and won't be flagged for deletion.

How does the module distinguish between original images and cache files in the database?

The module uses signed entity-type IDs as a convention. Original product images receive positive product type IDs (e.g., 4), while cache files receive negative values (e.g., -4). This allows the cleanup grid to display the file type and prevents mixing the two categories during batch operations.

Can these actions delete files automatically, or do they just identify them?

Both actions are identification-only processes. They populate the fb_imagecleaner_image table with candidates for deletion. Administrators must review the discovered files in the admin interface and explicitly trigger the deletion action. This safety mechanism prevents accidental removal of images that might be referenced by custom code or external systems not visible to the standard attribute and gallery queries.

What file paths does the Image Cleaner module scan?

According to the source code in FbimagecleanerController.php, the regular sync scans media/catalog/product for original uploads, while the cache sync scans media/catalog/product/cache for Magento's auto-generated thumbnails and resized variants. Both actions respect blacklist configurations defined in the helper class.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}