Image Resizer Extension

The Magebit Image Resizer Extension allows Magento 2 developers to effortlessly resize images programmatically, boosting website performance and improving user experience. This extension seamlessly integrates into projects, saving time and effort in managing visual assets.

Overview

The Image Resizer Extension provides comprehensive image processing capabilities for Magento 2, enabling developers to resize, transform, and optimize images with advanced features like watermarks, rotation, and responsive image generation.

Main Functionalities

Core Image Processing

Image Sources - Work with images from pub/media and module folders
Configuration - Configuration from view.xml and programmatic settings
Resize Operations - Resize images with various constraints and options

Advanced Features

Object-Fit Cover - Apply CSS object-fit: cover for images
Constraints - Keep constrain, frame, and aspect ratio settings
Transformations - Rotate images to specified angles
Background - Set custom background colors
Watermark - Apply watermarks with position and opacity control
Quality Control - Adjust image quality settings
Placeholder Support - Use placeholder images when needed

Installation

Install the Image Resizer extension using Composer.

Installation Command:

bash

composer require magebitcom/magento2-module-image-resizer

Post-Installation Steps:

bash

bin/magento setup:upgrade

Usage

View Models

The extension provides two main view models for different use cases:

ImageResizer: Main resizing entrance for daily use with comprehensive image processing capabilities.

CategoryImageResizer: Extends ImageResizer with additional methods to pass category-specific parameters.

Basic Usage

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

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

Basic Resizing Examples:

Image from pub/media directory:

php

<?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

<?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

<?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

<?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

<?php
$imageResizerViewModel = $viewModels->require(ImageResizer::class);
?>
<?= $categoryImageResizerViewModel
    ->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 sources with original and WebP format
Supports desktop/mobile and retina screens
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

<?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

<?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
    ); ?>

Advanced Usage Examples

Aspect Ratio Control

Maintain Original Aspect Ratio:

php

<?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()) ?>"/>

Constrain and Frame Options

Constrain Only (Prevent Upscaling):

php

<?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

<?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

<?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

<?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

<?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

<?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

<?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

<?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

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

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:

php

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

3. Initialization Time Attributes

All configurations allowed at initialization time:

php

<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

Code	Type	Default	Description
type	string	image	Used to specify image type (image, thumbnail). Can be any text. Right now used to only set watermarks from catalog setting.
width	int	null	Used to specify width. If null, takes value from height
height	int	null	Used to specify height. If null, takes value from width
aspect_ratio	bool	true	Guarantee, that image picture width/height will not be distorted.
constrain	bool	true	Guarantee, that image picture will not be bigger, than it was.
frame	bool	null	Guarantee, that image will have dimensions, set in $width/$height. Not applicable, if keepAspectRatio(false).
object_fit_cover	bool	false	Works same as CSS object-fit property. Fit the size and crop the image. This property ignores keepFrame and keepAspectRatio.
background	array	[255, 255, 255]	Set color to fill image frame with. The keepTransparency(true) overrides this (if image has transparent color).
transparency	bool	true	Keep transparency for image if any.
rotate	int	null	Rotate image into specified angle
watermark	string	null	Watermark image path
watermark_position	string	null	Watermark position on image. Available values: top-left, top-right, bottom-left, bottom-right, stretch, tile, center
watermark_size	string	null	Watermark size on image. Format is "INTxINT" (example: "20x20")
watermark_opacity	int	null	Watermark opacity on image.
placeholder	string	null	Placeholder image path.
quality	int	null	Quality of the image.
catalog_quality	bool	true	Use catalog config quality.
is_catalog_watermark	bool	true	Use catalog config watermark.

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

Cache Benefits:

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

Image Resizer Extension ​

Overview ​

Main Functionalities ​

Core Image Processing ​

Advanced Features ​

Installation ​

Usage ​

View Models ​

Basic Usage ​

Category Image Usage ​

Responsive Picture Generation ​

Responsive Picture with ImageId ​

Advanced Usage Examples ​

Aspect Ratio Control ​

Constrain and Frame Options ​

Object-Fit Cover ​

Quality Control ​

Image Rotation ​

Background Colors ​

Placeholder Images ​

Watermark Application ​

Configuration ​

Configuration Levels ​

1. Global Configurations ​

2. Image Type Configuration ​

3. Initialization Time Attributes ​

4. ViewModel Method Configuration ​

Configuration Options ​

Caching ​

Cache Management ​