Who this is for. The technical lead starting a new server-rendered site, before the first template is written. Afterwards you can make the choice on the criteria that matter, record why, and know what changing your mind later would cost.
Not a performance decision
Both engines compile templates to PHP and run the compiled code (Compilation and caching), and a page served from the page cache runs no template at all. What makes a Core dna page slow is the number of queries its templates cause and the weight of what it sends, in either engine (Measure first). There is no performance argument for either engine worth deciding on.
What should decide it
| Question | Points to Smarty when | Points to Twig when |
|---|---|---|
| What does the team already write? | The developers who will maintain the site know Smarty, or other Core dna sites they look after are Smarty | The developers know Twig from other work, and will read the upstream Twig manual for everything this guide does not cover |
| Is the site multi-language? | The platform registers four translation forms for Smarty, used directly in templates | The translator is there but no translation tag is: a site writes one macro over __.translate() and uses it (Translating in Twig). Workable, a little more verbose |
| Will anyone but developers edit template code? | Editors or administrators will maintain template code in jobs, discount conditions or shipping methods: Smarty's function list stops a call outside it from compiling | Only developers touch template code, so the absence of a sandbox costs a review step you would do anyway (Twig security) |
| How will mistakes surface? | You want a call to a method the record does not have to fail loudly, naming the method | You accept that such a call prints nothing, and test pages for empty output |
| How is the front end built? | Templates are mostly pages and partials | The front end is a component library that leans on embed, macros and isolated includes, which Twig has and Smarty does not |
| What does the rest of the estate use? | Shared partials, snippets and people move between this site and Smarty sites | They move between this site and Twig sites |
Two facts belong in the decision as well. Smarty is the platform's default, and most of the screens the platform ships, such as the sign-in page, exist only in Smarty, so a Twig site writes its own versions of the ones it uses (Overriding a platform template). And this documentation shows every template example in both engines, so neither choice leaves you without examples.
Can one site use both?
No. The engine is one setting for the whole site, Globals.template.engine, and every template the site renders goes through it: page templates, partials, error pages and the template code in the admin. There is no per-folder or per-file choice. A template written in the other dialect is read by the site's engine anyway: Twig syntax on a Smarty site breaks the page with a syntax error, and Smarty syntax on a Twig site is printed onto the page as text (A template written for the other engine).
The platform's own -twig templates are not a way around this. They are the platform shipping one screen twice and picking the copy that matches the site's setting; a site does not get to render one file with each engine.
The recommendation that follows: pick one engine per site, record the choice and the reason in the repository's README, and stay with it. Changing later means porting every template, which is a project, not a setting (Porting a template set).
What to read next
- Chose Smarty: the Smarty unit, starting with Smarty in Core dna.
- Chose Twig: the Twig unit, starting with Twig in Core dna.
- Multi-language either way: Translation and internationalisation before you write the first label.