How OpenMage Image Cleaner Handles Magento Placeholder Images During Product Synchronization

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 (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.

// 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.

// 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: 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: 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.

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