Guide 02 · Developer docs

Template languages: Smarty and Twig

Core dna renders server-side sites with Smarty or with Twig, one engine per site, and treats the two as peers. This guide is the one place both are documented: what they share, each engine's language and the platform's additions and limits, the two side by side, and translation.

L1–L2
Unit 01 · The shared model

Compilation and caching

The shared model Page 7 of 25 Updated

Both engines compile templates to PHP and keep the result in the site's cache folder on production, and recompile on every request elsewhere. Where compiled templates live, what clears them, the one difference between the engines that matters on production, and how this differs from the page cache.

Who this is for. The developer whose template change shows on one environment and not another, and the person deploying to production. Afterwards you will know when a template change takes effect, what clears the compiled templates, and when the compiled templates are not the cause at all.

Two engines, one arrangement

Neither engine reads a template file on every request. Each compiles the template into PHP the first time it is needed and runs the compiled version from then on. Where that compiled code is kept depends on the environment's mode, which is production unless the environment is configured otherwise:

SmartyTwig
Production: where compiled templates are keptThe site's .cache folder, one file per templateThe site's .cache folder, in two-letter subfolders
Production: a template file that changedRecompiled on the next request: Smarty compares the file's modification time with the compiled copyNot noticed: Twig keeps serving the compiled copy until the template cache is cleared
Every other environmentRecompiled on every request, in a temporary folderCompiled on every request, with no compiled cache

So on a development environment a saved template shows on the next request in either engine, and there is nothing to clear. On production the two engines differ, which matters only when a file reaches production without a deploy.

What clears the compiled templates

  • A deploy through version control. When a push is deployed, the platform clears the template cache, the page cache and the CDN cache of static files, for every environment that uses the same site folder. A deployed template change is live on the next request in either engine.
  • Clear Cache on the environment in the admin. It clears the page cache, the CDN cache of static files and the template cache, without a deploy.
  • Nothing else. A file copied to production by FTP clears nothing. Smarty notices the new file; Twig does not until someone clears the cache, and in both engines the page cache may still serve the old page.

The template cache is the compiled code and nothing more. Clearing it costs one compile per template on the next request that needs it, and loses no content.

When a change does not show

The compiled-template cache is rarely the cause. In order, check that the file was deployed and that it is the file the record uses (Which template renders a record), then the page cache and the CDN, then, on a Twig production site updated without a deploy, the template cache.

Compiled templates and the page cache

Two caches sit in the site's .cache folder, and they are easy to confuse:

Template cachePage cache (response cache)
HoldsEach template compiled to PHPWhole rendered responses, per URL
SavesParsing the templateRunning the controller, the queries and the template
Goes stale whenA template file changes (Twig on production)Content or a template changes and the cached page is still within its lifetime
A template controls it withNothing_response.preventCaching(), setCacheTTL(), addCacheVaryParameter()

The page cache behaves identically in both engines and has its own unit in Guide 12: The caching tiers and Cache invalidation.

What this means day to day

  • On a development environment, edit and reload. Nothing is compiled ahead or cached, so what you see is the file as it is now. Errors show with a stack trace.
  • On production, deploy through version control and the change is live on the next request. Do not patch templates on production by hand: on a Twig site the change will not show, and on either engine it is gone from version control.
  • After an emergency change by FTP, press Clear Cache on the environment, then commit the same change so the next deploy does not undo it.
  • The first request after a deploy is slower, because each template is compiled once; the visitors after it get the compiled version.
Go deeper
GuideThe caching tiers GuideGit-based deploy FAQMy template change is not appearing on the site How-toDiagnose "my change is not showing up"

Was this page helpful?

Your answer goes to the docs team.