How to Include Twig Partials in OpenCart 3.x Without Core Edits

A lot of developers solve this by editing system/library/template/ twig.php directly. It works, but every update becomes painful.

Here is a cleaner way: use an OCMOD that enables Twig includes while keeping core files untouched.

Download Modification

 

Why Twig include fails in default OpenCart 3.x

By default, OpenCart often renders Twig from an ArrayLoader only.
That means Twig knows the current template content, but it does not always know where to find other .twig files on disk.

So when you try:

{% include 'common/header.twig' %}

Twig may throw a “Could not load template” error.

 

The idea behind the fix

Use a ChainLoader :

• ArrayLoader for the main template (OpenCart behavior)
• FilesystemLoader for physical files in template directories

This gives Twig both:

1. the current compiled template code,
2. access to real file paths for includes.

 

Core code change concept

Inside system/library/template/ twig.php  , replace the loader section:

$loader = new \Twig\Loader\ArrayLoader(array($filename . '.twig' => $code));

with:

$loader1 = new \Twig\Loader\ArrayLoader([$filename . '.twig' => $code]);
$loader2 = new \Twig\Loader\FilesystemLoader([DIR_TEMPLATE]);
$loader = new \Twig\Loader\ChainLoader([$loader1, $loader2]);

Then Twig can resolve included files from your theme structure.

 

Best practice: do it as OCMOD, not core edit

Instead of modifying the core file directly:

• create install.xml with the search/replace operations,
• zip as your_name.ocmod.zip ,
• install from Extensions > Installer ,
• refresh Extensions > Modifications ,
• clear theme/Twig cache.

This keeps your project update-friendly and portable across stores.

 

Typical include usage in OpenCart templates

You can split large templates into reusable partials:

{% include 'extension/module/blocks/hero.twig' %}
{% include 'extension/module/blocks/features.twig' %}

This improves structure, readability, and reuse.

 

Troubleshooting tips (very important)

If you still get Could not load template ... , check these first:

• File really exists in the active theme folder.
• Active theme matches the path (e.g. dc_minimal vs designcart mismatch is common).
• Cache was cleared after modification refresh.
• Include path is correct relative to loader roots.

In one real case, everything in Twig was correct—but OpenCart was trying to load a module template from a different theme than the active one. The loader was fine; the path was wrong.

 

Final recommendation

Yes, enabling Twig includes in OpenCart 3.x is absolutely possible and a good idea.
The right approach is:

• implement via OCMOD ,
• use ChainLoader ( ArrayLoader + FilesystemLoader ),
• avoid direct core edits.

That gives you clean Twig partial architecture without sacrificing maintainability.