# How OpenMage Image Cleaner Handles Magento Placeholder Images During Product Synchronization

> Discover how OpenMage Image Cleaner protects Magento placeholder images during synchronization by excluding them from deletion and managing cache.

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

---

**The OpenMage Image Cleaner protects Magento's placeholder images by querying the `core_config_data` table for configured placeholder filenames and explicitly adding them to the "used" images list, while simultaneously excluding cached placeholder files from deletion during both product synchronization and cache cleanup operations.**

The `fballiano/openmage-image-cleaner` extension ensures that Magento's default placeholder images remain intact during automated media cleanup routines. Understanding how this tool interacts with **OpenMage Image Cleaner placeholder image configuration** settings is essential for maintaining product catalog integrity while safely reclaiming disk space from truly unused media files.

## How Placeholder Images Are Detected

### Querying the core_config_data Table

During the **Product Sync** job (`syncproductAction`), the controller reads Magento's configuration to identify which placeholder images are actively configured. The code queries the `core_config_data` table for all paths matching the pattern `catalog/placeholder/%_placeholder`.

### The Placeholder Path Pattern

Each returned value represents a filename (such as `small_image_placeholder.jpg`) that Magento displays when product images are missing. These filenames are stored without directory prefixes in the database, requiring the cleaner to reconstruct the proper path during synchronization.

## Protecting Placeholders During Product Synchronization

### The syncproductAction Implementation

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) (lines 84-89), the `syncproductAction` method fetches distinct placeholder values and prepends them with the `placeholder/` directory prefix before appending them to the `$db_images` array.

```php
// syncproductAction – fetch placeholder filenames from config
$placeholders = $db->fetchCol(
    "SELECT DISTINCT value FROM {$resource->getTableName('core_config_data')}
     WHERE path LIKE 'catalog/placeholder/%_placeholder'"
);
if ($placeholders) {
    foreach ($placeholders as $placeholder) {
        $db_images[] = "placeholder/{$placeholder}";
    }
}

```

By including these entries in `$db_images`, the subsequent `array_diff` operation that calculates `$unused_images` automatically excludes placeholder files. This prevents Magento's default placeholder graphics from being flagged for deletion even though they are not referenced in individual product attribute rows.

## Excluding Placeholders from Cache Cleanup

### The syncproductCacheAction Logic

During **Cache-Product Sync** (`syncproductCacheAction`), the cleaner scans cached image files but explicitly skips any paths containing `/placeholder/`. This logic appears in lines 34-36 of the same controller file.

```php
// syncproductCacheAction – skip placeholder files while scanning cache folder
foreach ($fs_images as $fs_image) {
    if (strpos($fs_image, '/placeholder/') !== false) {
        continue;               // <‑‑ do not treat as unused
    }
    // ... remaining logic for identifying unused cached images
}

```

This ensures that cached versions of placeholder images stored under `media/catalog/product/placeholder/` are never candidates for removal. The combined behavior guarantees that both original and cached placeholder pictures remain untouched throughout the synchronization workflow.

## Supporting Components and Helper Methods

The placeholder protection mechanism relies on utility functions defined in the extension's helper class:

- **[`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)**: Provides `scandirRecursive()` and `getMediaDirByEntityTypeId()` methods used by the controller while resolving placeholder paths and scanning media directories.
- **[`app/code/community/Fballiano/ImageCleaner/etc/system.xml`](https://github.com/fballiano/openmage-image-cleaner/blob/main/app/code/community/Fballiano/ImageCleaner/etc/system.xml)**: Defines the system configuration structure where Magento stores placeholder image filenames that the cleaner reads during synchronization.

## Summary

- The OpenMage Image Cleaner queries `core_config_data` for paths matching `catalog/placeholder/%_placeholder` to identify configured placeholder filenames.
- During `syncproductAction`, placeholder files are prefixed with `placeholder/` and added to the used images array to prevent deletion.
- During `syncproductCacheAction`, any cached file containing `/placeholder/` in its path is skipped entirely using `strpos()`.
- Placeholder images remain protected even though they are not referenced directly in product attribute tables, ensuring Magento's default "no image" graphics persist across cleanup operations.

## Frequently Asked Questions

### Where does OpenMage Image Cleaner find placeholder image filenames?

The extension queries Magento's `core_config_data` table using the SQL pattern `catalog/placeholder/%_placeholder` to retrieve the filenames configured for various product image attributes such as small, thumbnail, and base image placeholders.

### Why does the cleaner prefix placeholder files with "placeholder/"?

Magento stores only the bare filename in the database (e.g., `image.jpg`), but the physical files reside in `media/catalog/product/placeholder/`. The cleaner prepends `placeholder/` to align the database records with the actual filesystem paths used during the unused image comparison.

### How does the cache synchronization avoid deleting placeholder images?

In the `syncproductCacheAction` method, the code checks if the file path contains `/placeholder/` using `strpos($fs_image, '/placeholder/')`. If found, the loop continues to the next file, effectively excluding all cached placeholder images from the unused image detection logic.

### What database table stores Magento's placeholder configuration?

Magento stores placeholder image filenames in the `core_config_data` table under configuration paths following the pattern `catalog/placeholder/[attribute]_placeholder`, where `[attribute]` represents specific image types like `small_image` or `thumbnail`.