API Reference

Template

ThenLabs\Nate\Template — Main entry point. Loads and renders template files.

Method	Description
__construct(string $path)	Creates a new Template instance. The $path must point to an existing template file. Throws TemplateNotFoundException if the file doesn't exist.
render(array $data = []): string	Renders the template with the given data array. Returns the rendered HTML string. Each key in the data array becomes accessible as $this->key inside the template.

<?php
use ThenLabs\Nate\Template;

$template = new Template('/path/to/template.tpl.php');
$output = $template->render([
    'title' => 'Hello',
    'items' => ['A', 'B', 'C'],
]);
echo $output;

Compiler

ThenLabs\Nate\Compiler — Core engine that processes template inheritance and variable access. Template files are executed within the Compiler's scope, so $this in templates refers to the Compiler instance.

Method	Description
__get(string $name): mixed	Magic getter. Retrieves a variable from the data array by name. The value is wrapped in a Data object and cached. Throws DataNotFoundException if the variable doesn't exist.
block(string $name): void	Begins defining a block. Captures all output until endBlock() into a Block object. Can be nested.
endBlock(): void	Ends the most recently opened block definition.
extends(string $path): void	Declares that this template inherits from another template at $path. Path is resolved relative to the current template's directory.
parent(): string	Returns the placeholder string <_parent/>, which is replaced with the parent block's content during compilation. Only valid inside a block() / endBlock() pair.
includeTemplate(string $path, array $data = []): string	Loads and renders another template file, passing the provided data. Returns the rendered output as a string. The path is relative to the current template file's directory.
compile(Template $template, array $data): self	Main compilation method. Called by Template::render(). Processes the template, resolves inheritance and blocks, and stores the result.
getResult(): string	Returns the final compiled output after compile() has been called.

These methods are used inside template files (accessed via $this):

<?php $this->extends('layout.tpl.php') ?>

<?php $this->block('content') ?>
    <h1><?= $this->pageTitle ?></h1>
    <?= $this->includeTemplate('sidebar.tpl.php', ['items' => $this->navItems]) ?>
<?php $this->endblock() ?>

Data

ThenLabs\Nate\Data — Wrapper for variable values that provides auto-escaping, raw output, and iteration support. Implements IteratorAggregate and ArrayAccess.

Method	Description
__toString(): string	Converts the value to a string with HTML escaping applied (htmlspecialchars($value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8')). This is called automatically when you use <?= $this->var ?>.
raw(): mixed	Returns the original unescaped value. Use this when you need to output raw HTML.
getIterator(): Traversable	Returns an iterator where each value is wrapped in a new Data object, preserving nested auto-escaping. Throws NonIterableDataException if the underlying value is not iterable.

<!-- Auto-escaped: -->
<?= $this->userInput ?>

<!-- Raw output (unescaped): -->
<?= $this->trustedHtml->raw() ?>

<!-- Iteration with auto-escaped values: -->
<?php foreach ($this->items as $item) : ?>
    <li><?= $item ?></li>
<?php endforeach ?>

Block

ThenLabs\Nate\Block — Value object that stores block information during template compilation.

Property	Type	Description
$name	string	The name of the block.
$content	string	The captured content of the block.
$id	int	Numeric ID used for marker replacement (e.g., <_block_1>).
$parent	?Block	Reference to the parent block when blocks are nested.
$prev	?Block	Reference to the previous block with the same name (for inheritance override chain).

Config

ThenLabs\Nate\Config — Configuration class for customizing Nate's behavior.

Method	Description
getDataClass(): string	Returns the fully qualified class name used for wrapping data values. Defaults to Data::class. Can be overridden to provide custom value wrapping.

Exceptions

Exception	Description
NateException	Base exception class for all Nate errors. Extends \Exception.
TemplateNotFoundException	Thrown when a template file path does not point to an existing file.
DataNotFoundException	Thrown when accessing a variable that was not passed in the data array.
NonIterableDataException	Thrown when trying to iterate over a Data object that wraps a non-iterable value.

<?php
use ThenLabs\Nate\Template;
use ThenLabs\Nate\Exception\TemplateNotFoundException;
use ThenLabs\Nate\Exception\DataNotFoundException;

try {
    $template = new Template('/path/to/template.tpl.php');
    echo $template->render(['name' => 'World']);
} catch (TemplateNotFoundException $e) {
    echo 'Template not found: ' . $e->getMessage();
} catch (DataNotFoundException $e) {
    echo 'Missing variable: ' . $e->getMessage();
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}