Image Resizer Extension ​

The Image Resizer resizes, crops and converts images at render time. A template asks a view model for the size it needs; the module writes the file into pub/media/image_resizer/cache, stores the path in Magento cache and returns a URL. The size comes from a view.xml image role, from the call itself, or from both, with the call winning.

On top of single files it builds the responsive <picture> markup a theme needs: one source per breakpoint tier, WebP and optionally AVIF conversions, retina candidates, and a CLI command that generates all of it before the first visitor asks for it.

What it does ​

• Image sources - files under pub/media, and assets in a module's web directory
• Sizing - width, height, or either one alone, with control over aspect ratio, upscaling and framing
• Cropping - object_fit_cover, which behaves like the CSS object-fit: cover property
• Format conversion - WebP always, AVIF when enabled, each with its own quality setting
• Responsive markup - <picture> output, or the same data as an array for client-side rebuilds
• Transformations - rotation, background colour, transparency and watermarks
• Fallbacks - a placeholder image when the source file is missing
• Pregeneration - a CLI command that warms every registered image source, inline or through the queue

Installation ​

Install the Image Resizer extension using Composer.

Installation Command:

composer require magebitcom/magento2-image-resizer

Post-Installation Steps:

bin/magento setup:upgrade

Usage ​

View Models ​

The extension exposes two view models:

ImageResizer: The entry point for everyday use. It carries the whole API: sizing, format conversion, responsive markup and the transformations below.

CategoryImageResizer: Extends ImageResizer with methods that take category-specific parameters, so a template does not have to look the image attribute up itself.

Basic Usage ​

File Path Formats: File paths can be specified in two formats:

1. Pub Media Path: style-guide/test1.jpg - located in pub/media/style-guide/test1.jpg
2. Module Asset: Magebit_StyleGuide::images/test1.jpg - located in module's web directory

Basic Resizing Examples:

Image from pub/media directory:

<?php
$imageResizerViewModel = $viewModels->require(ImageResizer::class);
?>
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('style-guide/test1.jpg')
    ->resize(400, 200)
    ->getUrl()) ?>"/>

Image from module asset:

<?php
$imageResizerViewModel = $viewModels->require(ImageResizer::class);
?>
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('Magebit_StyleGuide::images/test1.jpg')
    ->resize(400, 200)
    ->getUrl()) ?>"/>

Flexible Resizing (width or height only):

<?php
$imageResizerViewModel = $viewModels->require(ImageResizer::class);
?>
<!-- Height only (width will match) -->
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('Magebit_StyleGuide::images/test2.jpg')
    ->resize(height: 200)
    ->getUrl()) ?>"/>

<!-- Width only (height will match) -->
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('Magebit_StyleGuide::images/test2.jpg')
    ->resize(width: 200)
    ->getUrl()) ?>"/>

Category Image Usage ​

Use the specialized CategoryImageResizer for category-specific image processing:

<?php
$categoryImageResizerViewModel = $viewModels->require(CategoryImageResizer::class);
?>
<img src="<?= $categoryImageResizerViewModel
   ->category(20)
   ->resize(300, 200)
   ->keepFrame(true)
   ->getUrl(); ?>"/>

Category Method Parameters:

• int|CategoryInterface $category - Category ID or category model
• string $imageAttribute - Image attribute (default: image)
• string $imageId - Image ID
• array $attributes - Additional attributes

Responsive Picture Generation ​

Generate responsive picture tags with sources for Desktop and Mobile using getResponsivePicture:

<?php
$imageResizerViewModel = $viewModels->require(ImageResizer::class);
?>
<?= $imageResizerViewModel
    ->constrainOnly(false)
    ->keepAspectRatio(false)
    ->keepFrame(false)
    ->getResponsivePicture(
        $block->getImagePath(),
        null,
        [
            'alt' => $escaper->escapeHtmlAttr($category->getName()),
            'aria-label' => $escaper->escapeHtmlAttr($category->getName()),
            'class' => 'hidden lg:block image object-cover',
            'picture_class' => 'flex'
        ],
        'category_block_list_widget',
        ['width' => 170, 'height' => 120],
        null
    ); ?>

Responsive Picture Features:

• Generates WebP sources for each tier, plus AVIF sources when AVIF output is enabled
• Serves the original format (JPEG/PNG) only through the <img> fallback, which carries its own retina srcset
• Supports desktop/mobile and retina screens, described by pixel density; see width descriptors for the w form and when density is the wrong tool
• Automatically adds _mobile suffix for mobile image IDs
• Uses desktop path for mobile if mobile path not provided
• Generates mobile sources only if size differs

Responsive Picture with ImageId ​

Using ImageId from view.xml:

<?php
$imageResizerViewModel = $viewModels->require(ImageResizer::class);
?>
<?= $imageResizerViewModel
    ->keepAspectRatio(false)
    ->constrainOnly(true)
    ->backgroundColor([0, 0, 0])
    ->getResponsivePicture(
        "Magebit_StyleGuide::images/test2.jpg", // Desktop image
        "Magebit_StyleGuide::images/test1.jpg", // Mobile image
        ['class' => 'mt-5'], // HTML attributes
        'category_block_list_widget' // ImageId from view.xml
    ); ?>

Without Mobile Image (Single Version):

<?php
$imageResizerViewModel = $viewModels->require(ImageResizer::class);
?>
<?= $imageResizerViewModel
    ->keepAspectRatio(false)
    ->constrainOnly(true)
    ->backgroundColor([0, 0, 0])
    ->getResponsivePicture(
        "Magebit_StyleGuide::images/test2.jpg", // Desktop image
        null, // No mobile image
        ['class' => 'mt-5'], // HTML attributes
        null, // No imageId
        ['width' => 768, 'height' => 480] // Custom dimensions
    ); ?>

Tablet tier and custom breakpoints ​

getResponsivePicture() accepts optional trailing parameters for a third (tablet) tier and custom breakpoints:

• ?string $tabletUrl and ?array $tabletSize add a tablet <source> between mobile and desktop. When only a size or a _tablet image id is given, the desktop URL is reused.
• A matching _tablet image id in view.xml is resolved automatically, in the same way _mobile already is.
• int $mobileMaxWidth (default 767) and int $tabletMaxWidth (default 1024) set the breakpoints, so they are no longer fixed.
• int $mobileMinWidth and int $tabletMinWidth (default 0) make a tier use a ranged min-width/max-width media query when set above zero. Tiers render narrowest first.

Responsive sources for client-side rebuilds ​

getResponsiveSources() returns the same responsive data as a structured array instead of HTML, so a script can rebuild the mobile/tablet/desktop sources on the client (for example after a swatch swap):

$sources = $imageResizerViewModel
    ->getResponsiveSources(
        'Magebit_StyleGuide::images/test2.jpg', // image path
        'product_card',                          // imageId from view.xml (uses its _mobile / _tablet variants)
        ['width' => 288, 'height' => 288]        // desktop size
    );
// [
//   'sources' => [ ['media' => ..., 'type' => ..., 'srcset' => ..., 'width' => ..., 'height' => ...], ... ],
//   'img'     => ['src' => ..., 'width' => ..., 'height' => ...],
// ]

It derives the mobile and tablet tiers from the image id's _mobile / _tablet variants and takes the same breakpoint parameters as getResponsivePicture(). The isObjectFitCover() accessor reports whether the store crops images to fill by default (the object_fit_cover setting), which is useful when deciding how to render a rebuilt source.

Width descriptors instead of 1x/2x ​

getResponsivePicture() and getResponsiveSources() describe each candidate by pixel density (1x, 2x). A density descriptor is a claim about the file, and it can be false. When the role is wider than the uploaded image and no frame is kept, Magento's adapter clamps the output to the source size, so the 2x candidate can carry the same pixels as the 1x one while telling the browser it has twice as many. The density form also assumes the image occupies the layout width its role was designed for, which stops being true as soon as the same role is reused in a narrower or wider slot.

getResponsiveSourcesWithWidths() returns the same tiers, renditions and array shape, with each candidate carrying a w descriptor that states the width the adapter actually wrote:

$sources = $imageResizerViewModel
    ->keepFrame(false)
    ->matchSourceAspectRatio(true)
    ->getResponsiveSourcesWithWidths(
        'catalog/product/t/p/track-pant.jpg', // image path
        'product_page_image_medium'           // imageId from view.xml, 626px wide
    );
// desktop srcset on a 1080x1340 upload: ".../626x777.avif 626w, .../1080x1340.avif 1080w"

• Candidates that collapse to the same width are emitted once. In the example above the retina candidate is a 1252px request against a 1080px upload, so it is reported as 1080w instead of a 2x that does not exist.
• Under keepFrame(true) the canvas is exactly the requested size, so the cap does not apply and the requested widths are reported.
• The sizes attribute stays with the caller. Only the template knows the layout, and a w srcset without sizes makes the browser assume the image is full-width.

The method takes the same signature as getResponsiveSources(), including the breakpoint parameters. getResponsiveSources() itself is unchanged, so existing callers keep their density descriptors.

The desktop key. Both methods also return desktop, the desktop tier's raw URLs keyed by rendition: standard, webp, retina, webp_retina, avif and avif_retina, each present only when that variant exists. Use it where there is no <picture> to pick a format, such as a CSS background-image. Re-requesting the same dimensions through init() is not equivalent: with matchSourceAspectRatio(true) the height is derived from the width by rounding, so a doubled height and a height derived from a doubled width can differ by a pixel, which writes a second rendition instead of reusing the one already generated.

AVIF output ​

The resizer can generate AVIF variants next to WebP and JPEG. AVIF files are typically 20 to 50 percent smaller than WebP at the same visual quality, so browsers that support the format download less. The feature is off by default and is enabled per store under Stores > Configuration > Advanced > System > Images Upload Configuration.

When enabled:

• Every breakpoint tier gets a <source type="image/avif"> row before the WebP one, each with standard and retina (2x) candidates. Browsers pick the first format they support, so AVIF-capable browsers use AVIF and the rest fall through to WebP.
• getResponsiveSources() returns the AVIF rows in the same order, and the Venta theme preloads the first known format of each tier, so LCP preloads follow the AVIF/WebP choice automatically.
• AVIF quality is configured independently of the JPEG and WebP quality settings (default 60), in admin or through the avif_quality view.xml var.

Encoding uses GD, which must be compiled with AVIF support. When GD cannot encode AVIF, the format is skipped without errors and the picture serves WebP and JPEG as before, so the toggle is safe to enable on any server. A status panel under the toggle reports whether the server can encode AVIF, so support is visible before enabling.

The panel lists the active image processor, the PHP GD extension, GD AVIF support, and the ImageMagick engine (a later addition). Check these rows first if AVIF images are not being generated.

When the server's GD is not compiled with AVIF support, the GD AVIF support row shows Missing and the detail explains what to fix. AVIF is skipped and the pictures serve WebP and JPEG as before.

Advanced Usage Examples ​

Aspect Ratio Control ​

Maintain Original Aspect Ratio:

<?php
$imageResizerViewModel = $viewModels->require(ImageResizer::class);
?>
<!-- Aspect ratio = true (default) -->
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('Magebit_StyleGuide::images/test3.jpg')
    ->resize(100, 300)
    ->keepAspectRatio(true)
    ->getUrl()) ?>"/>

<!-- Aspect ratio = false (distorted) -->
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('Magebit_StyleGuide::images/test3.jpg')
    ->resize(100, 300)
    ->keepAspectRatio(false)
    ->getUrl()) ?>"/>

Match the Source Aspect Ratio:

matchSourceAspectRatio(true) recomputes the height from the uploaded file's own proportions at the width the role declares, so the declared height acts as a hint rather than a target. Use it for slots that accept uploads of mixed aspect ratios, such as banners and CMS images: the image keeps its appearance, and because the resizer still reports concrete dimensions the slot reserves the right box and does not shift the layout.

cms_image_hero is one of the four Venta CMS image roles, added in 1.7.1.

<?= $imageResizerViewModel
    ->keepFrame(false)
    ->matchSourceAspectRatio(true)
    ->getResponsivePicture(
        'wysiwyg/home/hero.jpg',
        null,
        ['alt' => $escaper->escapeHtmlAttr($title)],
        'cms_image_hero'
    ); ?>

Constrain and Frame Options ​

Constrain Only (Prevent Upscaling):

<?php
$imageResizerViewModel = $viewModels->require(ImageResizer::class);
?>
<!-- Constrain only = true (won't exceed original size) -->
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('Magebit_StyleGuide::images/test2.jpg')
    ->resize(800)
    ->constrainOnly(true)
    ->backgroundColor([0, 0, 0])
    ->getUrl()) ?>"/>

<!-- Constrain only = false (can exceed original size) -->
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('Magebit_StyleGuide::images/test2.jpg')
    ->resize(800)
    ->constrainOnly(false)
    ->backgroundColor([0, 0, 0])
    ->getUrl()) ?>"/>

Frame Control:

<?php
$imageResizerViewModel = $viewModels->require(ImageResizer::class);
?>
<!-- Frame = true (exact dimensions with background) -->
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('Magebit_StyleGuide::images/test2.jpg')
    ->resize(800)
    ->keepFrame(true)
    ->backgroundColor([0, 0, 0])
    ->getUrl()) ?>"/>

<!-- Frame = false (natural dimensions) -->
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('Magebit_StyleGuide::images/test2.jpg')
    ->resize(800)
    ->keepFrame(false)
    ->backgroundColor([0, 0, 0])
    ->getUrl()) ?>"/>

Object-Fit Cover ​

CSS Object-Fit Behavior:

<?php
$imageResizerViewModel = $viewModels->require(ImageResizer::class);
?>
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('Magebit_StyleGuide::images/test2.jpg')
    ->resize(800, 200)
    ->setObjectFit(true)
    ->getUrl()) ?>"/>

Quality Control ​

Custom Image Quality:

<?php
$imageResizerViewModel = $viewModels->require(ImageResizer::class);
?>
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('Magebit_StyleGuide::images/test2.jpg')
    ->quality(1) // Very low quality for demonstration
    ->getUrl()) ?>"/>

Image Rotation ​

Rotate Images:

<?php
$imageResizerViewModel = $viewModels->require(ImageResizer::class);
?>
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('Magebit_StyleGuide::images/test2.jpg')
    ->rotate(90) // Rotate 90 degrees
    ->getUrl()) ?>"/>

Background Colors ​

Custom Background Colors:

<?php
$imageResizerViewModel = $viewModels->require(ImageResizer::class);
?>
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('Magebit_StyleGuide::images/test1.jpg')
    ->resize(200, 200)
    ->backgroundColor([255, 0, 255]) // Magenta background
    ->keepFrame(true)
    ->getUrl()) ?>"/>

Placeholder Images ​

Custom Placeholders:

<?php
$imageResizerViewModel = $viewModels->require(ImageResizer::class);
?>
<!-- Default catalog placeholder -->
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('non_existing_image_path')
    ->getUrl()) ?>"/>

<!-- Custom placeholder -->
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('non_existing_image_path')
    ->placeholder('Magebit_StyleGuide::images/test4.png')
    ->getUrl()) ?>"/>

Watermark Application ​

Add Watermarks:

<?php
$imageResizerViewModel = $viewModels->require(ImageResizer::class);
?>
<img src="<?= $escaper->escapeUrl($imageResizerViewModel
    ->init('Magebit_StyleGuide::images/test2.jpg')
    ->watermark(
        'Magebit_StyleGuide::images/test4.png', // Watermark image
        'center', // Position: top-left, top-right, bottom-left, bottom-right, stretch, tile, center
        '100, 100', // Size: "width, height"
        20 // Opacity: 0-100
    )->getUrl()) ?>"/>

Configuration ​

Configuration Levels ​

The extension operates with multiple levels of configuration, where lower levels override higher ones:

1. Global Configurations ​

Set default values for all resized images (e.g., background color for all images).

File: app/design/frontend/Vendor/theme/etc/view.xml

<view xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/view.xsd">
   <vars module="Magebit_ImageResizer">
      <!-- CONFIGURATIONS GOES THERE -->
      <var name="background">255,255,255</var>
   </vars>
</view>

2. Image Type Configuration ​

Set values for groups of images when same configs must be applied to multiple images.

• Allowed Configs - width, height, constrain, frame, aspect_ratio, transparency, background

File: app/design/frontend/Vendor/theme/etc/view.xml

<media>
     <images module="Magebit_ImageResizer">
         <image id="custom_image_1" type="image">
             <width>30</width>
             <height>30</height>
             <constrain>true</constrain>
             <frame>false</frame>
             <aspect_ratio>true</aspect_ratio>
             <transparency>false</transparency>
             <background>0,0,0</background>
         </image>
     </images>
</media>

Usage with Image ID:

<img src="<?= $imageResizerViewModel
              ->init('Magebit_StyleGuide::images/test.jpg', 'custom_image_1')
              ->getUrl(); ?>"/>

3. Initialization Time Attributes ​

All configurations allowed at initialization time:

<img src="<?= $imageResizerViewModel
               ->init('Magebit_StyleGuide::images/test.jpg', 'custom_image_1', [
                  \Magebit\ImageResizer\Model\Config::VIEW_XML_ATTRIBUTE_WIDTH => 100,
                  \Magebit\ImageResizer\Model\Config::VIEW_XML_ATTRIBUTE_CONSTRAIN => false,
                  \Magebit\ImageResizer\Model\Config::VIEW_XML_VAR_ATTRIBUTE_ROTATE => 90
               ])
               ->getUrl(); ?>"/>

4. ViewModel Method Configuration ​

The most preferred way to set configurations via viewModel methods.

Configuration Options ​

Admin Configuration ​

The extension adds its admin fields under Stores > Configuration > Advanced > System > Images Upload Configuration:

• Image Resizer WebP Quality (system/upload_configuration/magebit_image_resizer_webp_quality) - WebP compression quality, 1 to 100, default 80. Store-scoped. Changing it regenerates cached WebP, since the value is part of the cache key.
• Enable Image Resizer Logger - Turns on the extension's own logging.
• Enable Image Resizer Debug Logging - Depends on the logger. When off, resizer errors are condensed to a single-line summary; when on, full stack traces are logged.

• Enable Image Resizer AVIF Output (system/upload_configuration/magebit_image_resizer_avif_enabled) - Generates AVIF variants alongside WebP and serves them first in responsive pictures. Requires GD compiled with AVIF support; skipped silently when unavailable. Off by default. Enabling changes image cache paths, so the image cache regenerates.
• Image Resizer AVIF Quality (system/upload_configuration/magebit_image_resizer_avif_quality) - AVIF compression quality, 1 to 100, default 60. Store-scoped and part of the cache key, like the WebP quality. Shown only while AVIF output is enabled.

Pre-generating responsive images (CLI) ​

Responsive WebP, AVIF (when enabled) and retina variants are generated on demand the first time an image is requested. To warm them ahead of time, for example after a deployment or after enabling AVIF, run:

bin/magento catalog:images:pregenerate

The command walks every registered image source and generates its variants, showing a progress bar per source. In a Venta install the theme registers six: product cards, lifestyle images, widget images, category images, CMS responsive images and PDP gallery images. The last two ship with Venta 1.7.1.

Add --async to publish the work to the message queue instead of processing inline, then run the consumer:

bin/magento catalog:images:pregenerate --async
bin/magento queue:consumers:start magebit.image_resizer.responsive_generate --single-thread --max-messages=1000

This is separate from core catalog:images:resize. A module registers the images it wants pre-generated by implementing Magebit\ImageResizer\Api\ResponsiveImageSourceProviderInterface (getLabel() and getJobs()) and declaring it in di.xml.

WebP and AVIF are encoded in a single pass directly from the resized image, rather than re-encoding a JPEG, which avoids a second round of lossy compression.

Matching the storefront's cache keys ​

Pre-generation only pays off when it writes the same files the storefront asks for. Every resize option is part of the rendition path, so a provider whose job differs from its template in one flag warms a set of files nothing ever requests, and the first visitor still resizes on the fly.

Magebit\ImageResizer\Model\ResponsiveImage\Job takes two optional flags for the cases where the storefront call deviates from the role's view.xml defaults:

• $objectFitCover states the object-fit setting the template actually reads, instead of inheriting the resizer's own configuration.
• $constrainOnly states the constraint the template passes. It matters for a framed role whose canvas is larger than the upload: with constrain left at its default the adapter clamps the paste to the source size and centres it on the frame, so most of the requested pixels are background.

Both default to null, which keeps the role's own flags, so existing providers need no change. The async payload carries them as well, so --async and an inline run produce the same cache keys.

Caching ​

Cache Management ​

All resized images are located in pub/media/image_resizer/cache. Paths to resized images are stored in Magento cache.

Cache Behavior:

• If resized file doesn't exist or Magento cache is cleared, images will be resized again
• Cache can be cleared from Admin panel: System > Cache Management > Pregenerated resized images files
• Since 0.1.14 the clean action is gated by the module-owned ACL resource Magebit_ImageResizer::clean_resized_images, so it can be granted to a dedicated admin role.

Cache Benefits:

• Improved performance through cached resized images
• Automatic regeneration when cache is cleared
• Centralized cache management through Magento admin