Latte Templating Engine

Latte organizes blocks into three primary runtime layers. When you look up a block by name, Latte resolves it by checking the local layer first, then falling back to the top layer: blocks[LayerLocal][$name] ?? blocks[LayerTop][$name].

The Layers

• LayerTop (integer 0): The default layer for blocks defined at the template top level or within an {embed}. Most blocks reside here.
• LayerLocal ('local'): Targeted only when using the local keyword (e.g., {block local name} or {define local name}).
• LayerSnippet ('snippet'): Used for snippet-based rendering.

Block vs. Define

• {block}: Registers a block and also renders it in place.
• {define}: Only registers the block without rendering it.

When you use {include X from 'target'} (e.g., to render a specific block from another template), Latte executes target->render('X'). This renders only that specific block, not the template's main() method. This has significant implications for what is available during that render:

• {import} requirements: For an imported block to be available via {include ... from}, the {import} statement must be located in the template head. If any content exists before the {import}, it is pushed into main(), which is not executed during a single-block render, causing the include to fail.
• Intermediate local blocks: A block marked as local in an intermediate template in an inheritance chain is not available via lookup from a child. Only LayerTop merges up. The lookup always runs on the topmost parent, so only the topmost parent's LayerLocal is checked.

Latte transforms template source code into a PHP class through several stages:

1. Source
2. TemplateLexer: Tokenizes the source.
3. TemplateParser (including TemplateParserHtml and TagParser): Converts tokens into an Abstract Syntax Tree (AST).
4. AST Passes: The AST is traversed by various passes (e.g., for security or optimization).
5. TemplateGenerator: Converts the processed AST into PHP code.
6. PHP Class: The final output is a compiled PHP class.

Note that in-tag content is tokenized by a separate TagLexer, and TagParser is a generated LALR parser driven by TagParserData.

When using the {spaceless} tag, nesting multiple tags does not create multiple output buffers. Instead, the minifier uses a static depth counter to manage the process-global output buffering:

• The start() method increments a static $depth counter.
• Only the outermost call triggers the actual ob_start.
• The end() method flushes the buffer only when the depth returns to 0.

This ensures that nested {spaceless} blocks are treated as a single minification scope.

When an entire HTML attribute is generated from an expression (using Html\ExpressionAttributeNode), it bypasses the standard Escaper state machine. Instead, it uses specific Runtime\HtmlHelpers::format*Attribute methods determined at compile time.

The attribute type is determined by the attribute name (via classifyAttributeType) or forced by modifiers:

• Attribute Modifiers:
  • |toggle: Forces a specific attribute type.
• JSON: The |json modifier can be used, but it must be the last modifier in the chain.

These formatters (a "third layer" of escaping) handle their own logic, such as escapeAttr or JSON smart-quoting, to ensure that values like false in a hidden attribute are handled correctly according to HTML specifications.

AuxiliaryNode (available in area and expression variants) allows you to carry a closure as its print method. The body of this closure is opaque to compiler passes, meaning passes cannot see or rewrite the PHP it emits.

Security Warning: Because the closure body is invisible to security passes, you must never bake user-provided expressions directly into the closure. Instead, pass any user-controlled nodes into the AuxiliaryNode via its separate $nodes list, which remains traversable via &getIterator.

The Latte sandbox does not guard against implicit object-to-string coercion. While an explicit call like {$obj->__toString()} is blocked, the following will still trigger __toString() even if the method is not allowed by the Policy:

• Direct interpolation: {$obj}
• Concatenation
• String interpolation
• (string) casts
• Filters
• Loose comparisons

This is a deliberate design decision. The security responsibility lies with the host: do not expose objects with dangerous __toString implementations to the template engine.

Latte provides special tags to reference the current or parent block context:

Static Blocks

Inside a block with a static name, {include parent} and {include this} resolve the name at compile time based on the closest enclosing block.

Dynamically Named Blocks

Inside a block with a dynamic name, the compiler cannot resolve the name at compile time. Instead, the runtime retrieves the name from Template::$renderingBlocks (a stack of names currently being rendered).

Warning on Nesting: If you nest {include parent} inside a dynamic block that is itself inside a static block, the tag will refer to the dynamic block's runtime name. It will not automatically skip the dynamic block to find the outer static block unless the tag includes a from clause (which requires a compile-time name).

Latte uses different ordering mechanisms for Passes and Tags:

Passes

Passes are topologically sorted across all extensions using Helpers::sortBeforeAfter. You can use the Extension::order($subject, before:, after:) method to return a marker. Using '*' as a value for before or after means the pass will be positioned relative to all other passes (e.g., before: '*' runs before every other pass).

Tags

Tags follow a last-registered-wins rule. TemplateParser::addTags overwrites existing entries for a tag name. If two extensions define the same tag, the one registered later will take effect. Note that before/after markers do not affect tag registration priority; they are dropped for {tag} parsers.