# Sync Product Cache vs Regular Product Sync in OpenMage Image Cleaner

> Understand the OpenMage Sync Product Cache vs Regular Product Sync. Learn how to identify orphaned images and stale derivatives efficiently to clean your media storage.

- Repository: [Fabrizio Balliano/openmage-image-cleaner](https://github.com/fballiano/openmage-image-cleaner)
- Tags: deep-dive
- Published: 2026-03-01

---

**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`](https://github.com/fballiano/openmage-image-cleaner/blob/main/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`](https://github.com/fballiano/openmage-image-cleaner/blob/main/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`](https://github.com/fballiano/openmage-image-cleaner/blob/main/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.