How to Configure Wildcard Blacklist Patterns in OpenMage Image Cleaner to Exclude Files or Folders

Configure wildcard blacklist patterns in the OpenMage Image Cleaner by entering one pattern per line in the admin configuration at System → Configuration → Advanced → Image Cleaner, using glob wildcards (* and ?) relative to the media directory.

The fballiano/openmage-image-cleaner extension provides a robust mechanism for excluding specific files and directories from cleanup operations through configurable wildcard blacklist patterns. Understanding how to properly configure these patterns ensures that critical assets remain protected while orphaned images are removed.

Understanding the Blacklist Configuration

Configuration Storage Location

The blacklist is stored in the Magento configuration node admin/fb_image_cleaner/blacklist. This value is defined in app/code/community/Fballiano/ImageCleaner/etc/system.xml (lines 29‑38), which renders a textarea in the admin panel where you can enter exclusion patterns.

Pattern Syntax and Wildcards

Patterns use standard glob syntax relative to the media directory:

• * matches zero or more characters
• ? matches exactly one character
• One pattern per line
• Paths are case‑sensitive and must reflect the actual directory structure under media/

Example patterns:

• wysiwyg/landing*/*.jpg – excludes all JPG files in any subfolder starting with "landing" under media/wysiwyg
• wysiwyg/images2021 – excludes the entire folder media/wysiwyg/images2021 and all contents
• catalog/product/*/thumb_*.png – excludes PNG thumbnails in any product subfolder

How the Blacklist Filtering Works Internally

The filtering logic resides in app/code/community/Fballiano/ImageCleaner/Helper/Data.php.

Retrieving Patterns

At line 78, the helper fetches the raw configuration value:

$blacklist = Mage::getStoreConfig('admin/fb_image_cleaner/blacklist');

Line 84 splits the textarea content into an array using a regular expression that handles different line endings:

return preg_split('/\r\n|\r|\n/', $blacklist);

Matching Logic

During the recursive scan of the media directory, the helper checks each discovered path against every pattern. Lines 88‑90 perform the match using PHP’s fnmatch() function:

if (fnmatch('*/' . $blacklisted_pattern, $path)) {
    return true;
}

If fnmatch returns true, the file or folder is flagged as blacklisted and excluded from the cleanup results.

Step-by-Step Configuration Guide

Adding Patterns via the Admin Panel

1. Navigate to System → Configuration → Advanced → Image Cleaner.

2. Locate the Files/folders blacklist textarea.

3. Enter one pattern per line, for example:

   wysiwyg/landing*/*.jpg
   wysiwyg/images2021
   custom/keep-me.png

4. Click Save Config.

5. The next time you run the Image Cleaner scan, these paths will be ignored.

Programmatic Pattern Validation

If you need to test patterns before applying them, or integrate checks into custom scripts, use the helper methods directly:

/** @var Fballiano_ImageCleaner_Helper_Data $cleanerHelper */
$cleanerHelper = Mage::helper('imagecleaner');

// Load the blacklist defined in admin config
$patterns = $cleanerHelper->getBlacklistedPatterns();

// Example paths you want to test
$paths = [
    Mage::getBaseDir('media') . '/wysiwyg/landing-2022/banner.jpg',
    Mage::getBaseDir('media') . '/wysiwyg/images2021/logo.png',
    Mage::getBaseDir('media') . '/catalog/product/a/b/abc.jpg',
];

foreach ($paths as $path) {
    if ($cleanerHelper->isBlacklisted($path, $patterns)) {
        echo "$path is blacklisted → will be ignored\n";
    } else {
        echo "$path is allowed → will be processed\n";
    }
}

Extending Configuration in Custom Modules

To expose the same blacklist functionality in your own module’s configuration, define a textarea field in your system.xml:

<!-- In your module's etc/system.xml -->
<field id="blacklist" translate="label comment">
    <frontend_type>textarea</frontend_type>
    <label>Files/Folders Blacklist</label>
    <comment>
        Wildcards are allowed. One pattern per line, relative to the media folder.
        Example: "wysiwyg/old/*" or "catalog/product/*/thumb_*.jpg"
    </comment>
</field>

Summary

• The Image Cleaner blacklist is configured via the Magento admin at System → Configuration → Advanced → Image Cleaner using the admin/fb_image_cleaner/blacklist configuration node.
• Patterns use glob syntax (* for any characters, ? for single character) and must be specified one per line, relative to the media directory.
• The helper class Fballiano_ImageCleaner_Helper_Data in app/code/community/Fballiano/ImageCleaner/Helper/Data.php handles pattern retrieval (lines 78‑84) and matching via fnmatch() (lines 88‑90).
• Files or folders matching any active pattern are automatically excluded from the scan results and protected from deletion.

Frequently Asked Questions

What wildcard characters are supported in the blacklist patterns?

The Image Cleaner supports standard glob wildcards as implemented by PHP’s fnmatch() function. The asterisk (*) matches zero or more characters, while the question mark (?) matches exactly one character. These can be combined to create complex patterns such as wysiwyg/landing*/*.jpg to match all JPEG files in subfolders starting with "landing".

Are blacklist patterns case-sensitive?

Yes, the pattern matching is case-sensitive because it relies on PHP’s fnmatch() function without the FNM_CASEFOLD flag, and the comparison is performed against the actual filesystem path. You must ensure that your patterns match the exact casing of directories and files as they appear in the media folder. For example, Wysiwyg/ will not match a directory named wysiwyg/.

Can I blacklist entire directories or only specific files?

You can blacklist both entire directories and specific files. To exclude a complete directory and all its contents, specify the folder path relative to the media directory, such as wysiwyg/images2021. To exclude specific file types or naming patterns within directories, use wildcards like catalog/product/*/thumb_*.png. The recursive scan checks every discovered path against your patterns, skipping any match entirely.

How do I test if a blacklist pattern works before running a cleanup?

You can test patterns programmatically using the Fballiano_ImageCleaner_Helper_Data helper. Load the blacklist patterns via getBlacklistedPatterns(), then pass any absolute file path to isBlacklisted() to verify if it would be excluded. This allows you to validate your patterns against actual media paths before executing a destructive cleanup operation in the admin panel.

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