Magento 2 - How to call a custom phtml file in another phtml file, xml layout, static block and cms page?

Magento 2 - How to call a custom phtml file in another phtml file, xml layout, static block and cms page?

August 15, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Magento 2 - How to call a custom phtml file in another phtml file, xml layout, static block and cms page?

Magento 2: Embedding Custom PHTML Files

As a Magento developer working on a new theme, you may find yourself wanting to reuse custom PHTML files across different contexts like XML layouts, static blocks, CMS pages, or other PHTML files. This can help maintain code consistency and improve your store’s performance by reducing redundancy.

Understanding PHTML Files in Magento 2

PHTML stands for PHP Hypertext Preprocessor HTML, which is a server-side scripting language embedded within HTML. In Magento 2, PHTML files contain the actual HTML structure of a page along with any necessary PHP logic.

Calling a Custom PHTML File in Another PHTML File

To include one PHTML file inside another, you can use the include statement in your PHP code.

Let’s say you have a custom block called vendor_module.phtml located under app/code/Vendor/Module/view/frontend/templates/.

Your existing PHTML file (e.g., catalog_product_view.phtml) might look like this:

<?= $block->getChildHtml('content') ?>

To include the custom block, simply add the following line within your PHP logic:

echo $this->template->fetch('Vendor_Module::phtml');

Ensure you replace Vendor_Module with your actual module name and phtml with the specific file you want to include.

Including PHTML in XML Layouts

XML layouts define the structure of a Magento 2 page. To include a custom block, add it as a child element within the appropriate container.

Suppose you have an XML layout called catalog_product_view.xml located under app/code/Vendor/Module/view/frontend/layout/.

Your XML might look like this:

<referenceContainer name="content">
    <block class="Vendor\Module\Block\CustomBlock" template="Vendor_Module::custom_block.phtml"/>
</referenceContainer>

Here, we’re referencing the content container and adding our custom block (Vendor\Module\Block\CustomBlock) with a template path pointing to our PHTML file.

Embedding in Static Blocks

Static blocks allow you to create reusable content that can be inserted into various pages of your Magento 2 store. To add a PHTML file to a static block:

  1. Navigate to Content > Widgets.
  2. Click on the “Add New Widget” button.
  3. Choose “CMS Block” as the widget type.
  4. Select the appropriate page layout where you want to display the block (e.g., catalog product view).
  5. Under the “Template” field, enter your custom PHTML file path in the format Vendor_Module::custom_block.phtml.
  6. Save and apply the widget.

Including PHTML in CMS Pages

To include a PHTML file on a CMS page:

  1. Navigate to Content > Pages.
  2. Click “Add New Page” or edit an existing page.
  3. Switch to the HTML tab.
  4. Add your desired PHP logic to include the PHTML file (similar to the second example above).
  5. Save and preview the page.

Best Practices

  • Always use descriptive names for your custom PHTML files to avoid confusion.
  • Keep your PHTML files organized by module, following Magento’s folder structure.
  • Avoid hard-coding absolute paths in your PHP logic; instead, use relative paths or Magento’s template path helper ($this->template->fetch()).
  • Test your implementations thoroughly across different devices and browsers.

Conclusion

Incorporating custom PHTML files into various Magento 2 components is a powerful way to maintain code consistency and enhance performance. By understanding the different contexts where you can include these files, you’ll be well-equipped to build efficient and maintainable themes.

For more advanced topics in Magento development, consider checking out Laravel Company’s Magento 2 tutorials for a deeper dive into the platform’s capabilities.

Magento 2 Catalog Performance Extensions

Our network