Anatomy: a templater for PHP

HTML Templater for PHP.

Lightweight, simple but powerful templater for rendering HTML templates in PHP.

I believe that you'd like to

• keep your HTML clean and simple, and
• maintain the logic in PHP, not in HTML.

Table of Contents

• How rendering works
• Requirements
• Installation
• Getting Started
  • Tags
  • Predefined tags
  • Blocks & Containers
  • Detached mode
• Rendering contract and escaping
• Back compatibility
• Development roadmap

How rendering works

flowchart LR
    A["render(template, data)"] --> B{"Is data empty?"}
    B -- "yes" --> C["Return the original template unchanged"]
    B -- "no" --> D["Parse block definitions"]
    G["renderBlock(template, block, data)"] --> D
    D --> E["Render tags and containers"]
    E --> F["Rendered output"]

Loading

Inserted data is opaque and is never parsed as template source. The empty-data bypass and the different detached-block behavior are part of the public contract, not optimizations.

Requirements

PHP 8.0 and later.

Installation

composer require hokoo/templater

Getting Started

Here are some examples of how to use the templater.

🅰️ Tags

Example:

<div class="article">
    <h2>
        <!-- This is a tag named "title". -->
        {{title}}
    </h2>
    
    <div class="content">
        <!-- This is a tag named "content". -->
        {{content}}
    </div>

</div>

PHP code:

use iTRON\Anatomy\Templater;
$templater = new Templater();

return $templater->render( $html, [
    'title'   => 'The Best Title',
    'content' => 'Anything you want',
] );

The result will be:

<div class="article">
    <h2>
        <!-- This is a tag named "title". -->
        The Best Title
    </h2>
    
    <div class="content">
        <!-- This is a tag named "content". -->
        Anything you want
    </div>

</div>

Read more theory about Tags

Tag - a point in the template where you can insert a value. Tag should be considered as a placeholder for a value.

In the Anatomy's paradigm, the 'tag' is only entity that can be replaced with a value.

The tag is a string that starts with {{ and ends with }}.

Regular tags render raw values. Use {{tag|e}} for user-controlled HTML text or quoted HTML attribute values. Attribute placeholders must always be enclosed in quotes. See Rendering contract and escaping.

So, in the example above, the {{title}} and {{content}} are tags. Let's render the template with the values.

🅰️ Predefined tags

Example:

<div class="{{#class=[first|second|third]}}"></div>

PHP code:

$templater = new \iTRON\Anatomy\Templater();

$result = $templater->render( $html, [
    'class' => 0,
] );

The result will be:

<div class="first"></div>

Read more theory about Predefined Tags

Predefined tags are tags that can render only values predefined by the template.

Predefined tag's modifier can only accept an integer value as index of one of the predefined values (starting from 0). Any invalid modifier value (non-integer or integer that points beyond of the array) will be considered as 0.

A missing, negative, or out-of-range modifier is also considered as 0.

The default values' delimiter is |. You can change it by setting the delimiter property of the tag.

<div class="{{#class=[first!!second!!third] delimiter=[!!]}}"></div>

🅰️ Blocks & Containers

Example:

<div class="feed">
    <h1>{{title}}</h1>

    {{content}}
    
    <!-- This is a block named "article". -->
    [[#article]]
    <div class="article">
        <h2>{{title}}</h2>
    
        <div class="content">
            {{content}}
        </div>
    </div>
    [[/article]]
</div>

PHP code:

// This is a container. 
// It can contain blocks and texts.
$content = new \iTRON\Anatomy\Container();

// Let's put block "article" into the container.
$content->addBlock( 'article', [
    'title'   => 'The Best Title',
    'content' => 'Anything you want',
] );

// Another one.
$content->addBlock( 'article', [
    'title'   => 'There is no title',
    'content' => 'There is no content.',
] );

// Or you can add a plain text.
$content->addText( 'Plain text.' );

$templater = new iTRON\Anatomy\Templater();

return $templater->render( $html, [
    'title'   => "Feed's Title",
    'content' => $content
] );

The result will be:

<div class="feed">
    <h1>Feed's Title</h1>
    
    <!-- This is a block named "article". -->
    <div class="article">
        <h2>The Best Title</h2>
    
        <div class="content">
            Anything you want
        </div>
    </div>
    
    <div class="article">
        <h2>There is no title</h2>
    
        <div class="content">
            There is no content.
        </div>
    </div>
  
    Plain text.
  
</div>

Read more theory about Blocks & Containers

Blocks are a way to have a component-like structure in the template. You can consider blocks as a template inside a template.

You can define as many blocks as you want and render them in any order.

Each block definition must have a unique name. The same definition can be rendered repeatedly and recursively through nested containers.

You can put one block into another block. This is how you can create a nested structure without any restrictions on the depth of nesting.

🅰️ Detached mode

Since we consider blocks as an almost independent template, you can use blocks out of context of the main template.

Suppose, you need to render the "article" block from the template above in a different place. Great, there's no need to duplicate the block's code. Just render the block separately.

$templater = new \iTRON\Anatomy\Templater();

echo $templater->renderBlock(
    $html, 
    'article', 
    [ 
      'title' => 'Title',
      'content' => 'Content'
    ] 
);

The result would be:

<div class="article">
    <h2>Title</h2>
    
    <div class="content">
        Content
    </div>
</div>

Rendering contract and escaping

Calling render( $template, [] ) intentionally returns the original template without replacing tags, extracting blocks, or validating its syntax. Detached blocks are different: renderBlock() can render a hard-coded block with its default empty data array.

{{tag}} remains raw for version 4 compatibility. Use {{tag|e}} for HTML escaping:

$templater->render( '<p>{{message|e}}</p>', [
    'message' => '<strong>User text</strong>',
] );
// <p>&lt;strong&gt;User text&lt;/strong&gt;</p>

HTML escaping is not a substitute for JavaScript, CSS, or URL-specific encoding. In HTML attributes, always put an escaped placeholder inside quotes, for example data-label="{{label|e}}"; never use an unquoted placeholder. The complete value, error, block grammar, and security contracts are documented in Anatomy template language.

Back compatibility

Version 3 compatibility is deprecated as of 4.2 and is planned for removal in version 5. It receives compatibility fixes during the version 4 lifecycle but does not receive new features. Syntax older than version 3 is not supported.

To use v3 syntax, you have to instantiate the legacy version of the templater:

$templater = new \iTRON\Templater\Templater();

// Instead of
// $templater = new \iTRON\Anatomy\Templater();

Development roadmap

Version 4.2 is the current stable contract baseline. The next maintenance and major-version work, its dependencies, and the required decision gates are tracked in the development roadmap. Release history is kept in the changelog.