Ovewrite gallery.phtml file in Magento2 from custom module

Ovewrite gallery.phtml file in Magento2 from custom module

September 3, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Ovewrite gallery.phtml file in Magento2 from custom module

Overriding gallery.phtml File in Magento2 from Custom Module

Hello developers! Today, I’m going to guide you through overriding the gallery.phtml file from your custom module in Magento2. This is a common requirement when you want to customize how product images are displayed on the frontend.

Understanding Your Current Setup

You’ve already created a catalog_product_view.xml layout file under your module’s layout folder with the following content:

<page layout="1column" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">

    <body>
        <referenceBlock name="product.info.media.image" remove="true"/>
        <referenceContainer name="product.info.media">
            <block class="Magento\Catalog\Block\Product\View\Gallery"
                   name="product.info.media.image"
                   template="product/view/gallery.phtml"/>
        </referenceContainer>
    </body>
</page>

Your layout file is correctly configured to remove the default gallery block and replace it with a new instance of the same class, using your custom template.

The Current Issue

You mentioned that this setup is not rendering the desired file. When you change <referenceBlock name="product.info.media.image" remove="true"/> to false, it starts displaying the base image instead of the gallery images.

This issue suggests a potential problem with how Magento is resolving the template path for your custom block.

Resolving the Issue

1. Proper Path Resolution

The key lies in ensuring that Magento can correctly locate and render your custom gallery.phtml file. Here’s what you need to do:

Navigate to the directory structure of your module. You should have something like this under your module root folder:

app/code/Vendor/Module
└── view
    └── front-end
        └── template
            ├── Magento_Catalog
                └── product
                    └── view
                        └── gallery.phtml

Ensure that the gallery.phtml file is located inside the correct directories. It should be placed under your module name (Vendor_Module), then view, frontend, template, Magento_Catalog, product, and finally view.

2. Double-Checking Your XML Namespace

In your catalog_product_view.xml file, double-check that the namespace definition is correct:

<page layout="1column" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">

Specifically, ensure that you have the correct schema location for the xmlns:xsi namespace.

3. Clearing Cache

After making changes to layout XML files, always remember to clear your Magento cache:

php bin/magento cache:clean

Or if you’re using a Magento version before 2.4.0, use this command instead:

php bin/magento cache:flush

Additional Best Practices

1. Theme Fallbacks

If you’re working on a theme and want to override the same file from your theme, ensure you follow the proper directory structure for themes.

2. Use GetView() Properly

In your gallery.phtml template, use $this->getView() correctly to access relative paths when needed. For example:

<div class="product-image-gallery">
    <?php foreach ($block->getGalleryImages() as $_image): ?>
        <div class="gallery-item">
            <a href="<?php echo $this->escapeHtml($_image->getUrl()) ?>"
               title="<?php echo $this->escapeHtml(__('Zoom')) ?>">
                <img src="<?php echo $this->helper('Magento\Catalog\Helper\Image')->init($_image, 'product_page_image_small')->constrainOnly(TRUE)->getUrl() ?>"
                     alt="<?php echo $this->escapeHtml($_image->getLabel()) ?>"/>
            </a>
        </div>
    <?php endforeach; ?>
</div>

Conclusion

To summarize, overriding the gallery.phtml file from your custom module involves:

  1. Placing your template file in the correct directory structure.
  2. Ensuring your layout XML is configured correctly.
  3. Clearing Magento cache after making changes.

If you’re still having trouble or want to learn more about Magento 2 development, feel free to explore our comprehensive guides on https://laravelcompany.com/magento-2-development-tutorials. We cover everything from setup and configuration to advanced customizations and extensions.

Magento 2 Catalog Extensions Themes

Our network