How to override .phtml file in custom module of magento?

How to override .phtml file in custom module of magento?

August 29, 2026 · Illustrated author avatarBy Stefan Bogdanescu
How to override .phtml file in custom module of magento?

Overriding .phtml Files in Custom Magento Modules

As a senior developer working extensively with Magento, I often encounter situations where clients need to override existing .phtml files in their custom modules. The method you’ve attempted is on the right track, but let’s dive deeper into how to successfully achieve this.

The anatomy of your current approach

<checkout_onepage_index>
    <reference name="payment">
        <action method="setTemplate">
            <template>giftcard/checkout/onepage/payment.phtml</template>
        </action>
    </reference>
</checkout_onepage_index>

In your layout XML, you’ve used the setTemplate action to specify the path to your custom payment.phtml file. The giftcard namespace suggests that this is likely a gift card module. You’re pointing Magento’s renderer to use your custom template located at giftcard/checkout/onepage/payment.phtml.

Where did things go wrong?

The primary issue lies in the location of your override file. When you create an override for a core Magento template, it should be placed within your module directory under the template folder, following the default theme structure.

Your current approach places the file directly under the module’s root directory (giftcard), which isn’t recognized by Magento as a valid template location.

The correct way to override .phtml files

  1. Create the proper directory structure: Within your custom module (let’s assume it’s located at app/code/GiftCard for this example), you need to create the following directories:
GiftCard
├── etc
│   └── module.xml
└── view
    └── frontend
        └── Giftcard
            ├── template
            │   └── checkout
            │       └── onepage
            │           └── payment.phtml
  1. Update your layout XML: In the etc folder, open your module.xml file and ensure it includes this code:
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <sequence>
        <module name="Magento_Checkout"/>
    </sequence>
</config>

This tells Magento to load your module after the core Magento_Checkout module, ensuring your override takes precedence.

  1. Create and populate your template: Inside the view/frontend/Giftcard/template/checkout/onepage/ directory, create a new file called payment.phtml. This is where you’ll place your custom HTML code to override the core file.

  2. Clear cache: After creating or updating your file, make sure to clear Magento’s full page cache and browser cache to see the changes reflected on the frontend.

Why should you follow this approach?

By following the standard theme structure within your module, you’re adhering to Magento’s recommended best practices for overriding core templates. This ensures your code remains portable across different environments and upgrades, reducing the risk of conflicts or unexpected behavior.

If you’re looking for more advanced techniques like programmatic overrides using Plugins (https://laravelcompany.com/blog/magento-2-plugin-example), I recommend checking out our comprehensive guide on Magento 2 Plugin development. We cover everything from understanding the plugin architecture to creating effective plugins for extending core functionality.

In conclusion, successfully overriding .phtml files in a custom Magento module requires a clear understanding of the file structure and layout XML configuration. By following the recommended approach outlined above, you’ll be able to efficiently override templates without compromising your site’s stability or upgrade compatibility.

Remember to always keep your code organized and well-documented for easier maintenance and collaboration with your development team. Happy coding!

Checkout Extensions Themes Errors

Our network