Download the PHP package qoliber/tsuku without Composer

Tsuku (つく)

A lightweight PHP templating library for transforming data into ANY text format

Tsuku is a powerful template processing library built with a clean Lexer → Parser → Compiler architecture. Transform your data into CSV, XML, JSON, XSD, or any text format you need using simple, intuitive templates.

Perfect for e-commerce exports, API responses, configuration files, and data transformations.

📖 Documentation: tsukuru.dev

Features

• 🎯 Any text format: CSV, XML, JSON, YAML, TOML, HTML, Markdown, INI, XSD, or custom formats
• 🔄 Control flow: Loops (@for), conditionals (@if, @unless, @elseif, @else), pattern matching (@match)
• 🧮 Real conditions: and/or/not, &&/||/!, parentheses, in / not in
• 🪺 Deep nesting: Unlimited levels of nested directives
• 🎨 Smart object/array access: Automatic getter detection, method calls, property access
• 🔧 Custom functions and directives: Register your own @function() handlers and @block() ... @end directives
• 🎭 Widget support: Build Magento-style widgets with custom functions
• 🛠️ Clean architecture: Lexer → Parser → Compiler pipeline (AST-based)
• 🚀 PHP 8.1+: Modern PHP with zero dependencies
• ✅ Production-ready: 960 tests (including characterization tests against 1.3.0), 99.4% line coverage, 98.8% mutation score
• 📦 Predictable whitespace: directive-only lines vanish, content lines are kept exactly as written
• ⚡ Fast: Single-pass compilation, efficient AST walking
• 🔒 Type-safe: Full PHP 8.1+ type hints and strict types

Performance

Tsuku 1.4.0, PHP 8.3 run with php -n (no Xdebug, no OPcache), Intel Core Ultra 7 265K, Linux; median of 9 runs of php -n benchmarks/run-all.php:

Tsuku parses the template on every process() call and keeps no compiled cache: it is built for one render with a large output (exports, feeds, documents), not for thousands of small renders per second. For feeds too large to hold in memory use processToStream().

Run the benchmarks yourself (your hardware will differ):

Use -n, or at least switch Xdebug off: with Xdebug loaded (xdebug.mode=develop) the same benchmarks ran about 5x slower on the machine above. See tsukuru.dev/guide/performance.

Requirements

• PHP 8.1 or higher

Installation

Quick Start

Simple Variables

Loops with @for

Conditionals with @if and @else

Smart Object/Array Access

Custom Functions

Streaming Large Datasets

For large catalogs (10k+ rows) where holding the whole rendered output in memory is impractical, use processToStream. It renders the template incrementally — header once, each row in turn, footer once — and writes each piece through a callback as soon as it's ready.

Constraints:

• Template must contain exactly one top-level @for over the streaming variable. Multiple matches or nesting inside @if/@for throws.
• The streamed iterable is consumed once. Generators cannot be rewound.
• Memory usage is bounded by the size of the largest single piece (header, footer, or one row), regardless of total row count.
• In WARNING mode at most 1,000 warnings are kept per call (ProcessingContext::WARNING_LIMIT), so a warning on every row does not grow memory either; getWarningCount() returns the total.

Real-World Examples

CSV Export with Escaping

@csv() quotes only the values that need it. @number(value, 2) alone would print 1,299.50 - the thousands separator would split the price into two columns - so CSV templates pass the separators: @number(value, 2, ".", "").

XML Product Catalog

Tsuku escapes nothing on its own: use @xml(), @html(), @json() or @csv() for values that may contain special characters.

JSON with Commas Between Items

JSON allows no comma after the last element, so put the separator in front of every element but the first. In a list the loop key is 0 only for the first element (pass array_values($items) if the keys are different):

@json() prints a complete, quoted JSON string. More patterns: tsukuru.dev/examples/json-apis.

YAML Configuration

HTML Product List with XSS Protection

Template Syntax

Variables

Use {variableName} or {object.property} for dot notation:

Smart Object/Array Access: each segment of a path is read from an array by key; from an object Tsuku uses the first of these that exists: getX(), isX(), x(), then the public property x.

Details: tsukuru.dev/guide/variables.

For Loops

With key/value (value first, then key):

Conditionals

If/Else:

Unless:

Match (Pattern Matching):

Match with multiple values:

Else-if:

Conditions (in @if, @unless, @elseif and @?{...}):

Precedence from lowest to highest: or < and < not < comparisons, so not a == b means not (a == b). Operands are string and number literals, variable paths, function calls and parenthesised expressions; a condition may span several lines. and, or, not and in are keywords only as whole words, so product.order, inventory or notes are ordinary variables. true, false and null are not literals (they are looked up as variables, as in earlier versions): write @if(flag) / @if(not flag).

Malformed conditions (=, x - 1, a < b < c, a dangling and, an unknown function, ...) throw a ParseException (or FunctionNotFoundException) naming the line and column instead of rendering something wrong.

Built-in Functions

String functions:

Number functions:

Templates have no arithmetic: @number(qty * price, 2) prints 0.00 and a condition such as index < length(items) - 1 throws a ParseException. Compute derived values (line totals, margins) in PHP before rendering, or register a function.

Array functions:

Escaping functions:

Date/Utility functions:

Membership functions:

Custom Functions

Register your own:

Custom Directives

Directives wrap a block of the template. The handler receives the rendered body first, then the arguments (resolved like function arguments), and returns the output that replaces the block:

A directive can be written @name(arguments) ... @end or, without arguments, @name ... @end. Registered names take precedence over functions of the same name; built-in names (if, for, ...) cannot be registered. Errors thrown by a handler follow the strictness mode, like function errors.

Whitespace Control

Templates can be indented freely; the rules decide which whitespace around directives is output:

1. A line holding only directives (and spaces/tabs) produces no output at all - not its indentation, not its line break.
2. Indentation before @else, @elseif, @case, @default and @end at the start of a line is dropped.
3. A directive other than @end at the end of a content line takes that line break with it.
4. An @end that follows content on its line keeps the line break after it.
5. In an inline block (content before the opening directive on its line), whitespace containing a line break at the start of each branch is dropped - and at the end of each branch too when content follows the block's @end on its line. Single-line branches (@else out) stay exactly as written.

renders one row per product (WID-001,Available). \ line continuations still join lines first; \r\n line breaks are handled like \n. Full rules with examples: tsukuru.dev/guide/whitespace-control.

Escaping

@@ prints a literal @ (user@@example.com, @@media (max-width: 600px)). Braces need no escaping: {...} is a variable only when it contains a plain path, so JSON, CSS and Magento directives such as {{widget ...}} or {{media url="..."}} pass through unchanged. ({{name}} is { + the value of name + }; to print a literal {name} use @concat("{", "name}").)

Deep Nesting

Nest directives as deep as you need:

Architecture & Design

Tsuku uses a clean three-stage compiler pipeline inspired by traditional programming language design:

The Pipeline

1. Lexer (Lexical Analyzer)

What it means: "Lexer" comes from "lexical analysis" - breaking text into meaningful chunks

Location: src/Lexer/Lexer.php

The Lexer reads the raw template string character by character and breaks it into tokens (meaningful units):

Why? Makes parsing easier by converting a string into structured chunks.

2. Parser (Syntax Analyzer)

What it means: Builds a tree structure showing how pieces relate to each other

Location: src/Ast/Parser.php

The Parser takes tokens and builds an AST (Abstract Syntax Tree) - a tree structure representing the template's logical structure:

Why? The tree structure makes it easy to handle nesting and execute directives in the correct order.

3. Compiler (Code Generator)

What it means: Walks the tree and generates the final output

Location: src/Compiler/Compiler.php

The Compiler walks the AST tree using the Visitor Pattern and generates the output string:

Why? Clean separation: data lookup, conditionals, loops all handled in one place.

Key Concepts Explained

AST (Abstract Syntax Tree)

• A tree representation of your template structure
• Each node = one piece (text, variable, loop, condition)
• Example: @if(x)@for(items)...@end@end becomes a tree with IfNode containing ForNode

Node

• One element in the AST tree
• Types: TextNode, VariableNode, ForNode, IfNode, FunctionNode, etc.
• Each node knows how to compile itself

Token

• Smallest meaningful unit from Lexer
• Like words in a sentence
• Types: TEXT, VARIABLE, DIRECTIVE_IF, DIRECTIVE_FOR, etc.

Visitor Pattern

• Design pattern where nodes "accept" a visitor (the compiler)
• Allows separating tree structure from processing logic
• Each node has accept(NodeVisitor $visitor) method

Benefits of This Architecture

✅ Predictable whitespace - layout is decided once, while lexing; rendering never re-scans text ✅ Proper nesting validation - Parser builds correct tree or throws error ✅ Clean separation of concerns - Each stage has one job ✅ Easy to extend - Add new node types without breaking existing code ✅ Fast execution - Single pass through the tree ✅ Type safety - PHP 8.1+ types ensure correctness

Class Naming Conventions

Tsuku follows industry-standard naming for compiler components:

Naming Philosophy:

• Lexer/Parser/Compiler - Standard compiler pipeline terms
• Node suffix - Indicates AST node type (TextNode, IfNode)
• Registry suffix - Stores and manages items (FunctionRegistry)
• Visitor suffix - Implements visitor pattern (NodeVisitor)
• Exception suffix - Error types (TsukuException, ParseException)

How It All Works Together

This architecture is the same used by:

• Programming languages (PHP, JavaScript, Python)
• Template engines (Twig, Blade, Smarty)
• Markup processors (Markdown, BBCode)

Further Reading:

• Compilers: Principles, Techniques, and Tools (Dragon Book)
• Abstract Syntax Tree
• Visitor Pattern

Development

License

MIT License - see LICENSE file for details

Credits

Created by qoliber - Like a hummingbird (koliber), swift and precise in data transformation.

Tsuku (つく) means "to create" or "to make" in Japanese, reflecting the library's purpose of creating text output from data.