run-as-root / module-image-cache-migration

1.0.0 2026-10-30 15:33 UTC

Unknown License

Published on Packagist.org on 2026-11-04 13:53 UTC

README

Magento 2.4.9 changes resized product image hashes from HMAC-MD5 (using the encryption key) to plain MD5. This gives existing images new URLs and forces Magento to regenerate them.

This module renames existing cache directories to the new hashes and leaves relative symlinks at the old paths. Migrated images do not need to be regenerated, and both URLs keep working—including those in older emails.

Installation

composer require run-as-root/module-image-cache-migration

Usage

Run immediately after deploying the Magento upgrade, using the same crypt/key as before the upgrade:

bin/magento run-as-root:image-cache:migrate-hashes

Add --dry-run to preview changes. The command is safe to run multiple times.

Migration behavior

The command calculates old and new hashes from the view.xml image definitions of the themes used by every store.

• Renames old cache directories and creates relative symlinks at their original paths.
• If a new cache directory already exists, deletes it and its contents before replacing it with the old directory.
• Skips old paths that are already symlinks.
• Leaves unmatched directories untouched, including images with dimensions defined directly in code. Magento regenerates these on demand.

Notes

• The web server must allow symlinks in the media directory.
• Flush Catalog Images Cache removes both cache directories and symlinks, so old URLs may stop working.
• Old symlinks can be removed when the old URLs are no longer needed.