https://github.com/sedteam/xtemplatese
XTemplate SE (Seditio Edition)
https://github.com/sedteam/xtemplatese
engine php template-engine xtemplate
Last synced: 2 months ago
JSON representation
XTemplate SE (Seditio Edition)
- Host: GitHub
- URL: https://github.com/sedteam/xtemplatese
- Owner: sedteam
- License: bsd-3-clause
- Created: 2025-03-07T10:55:17.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-03-07T22:20:38.000Z (2 months ago)
- Last Synced: 2025-03-07T23:24:06.226Z (2 months ago)
- Topics: engine, php, template-engine, xtemplate
- Language: PHP
- Homepage: https://seditio.org
- Size: 56.6 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
XTemplate SE
============
Table of Contents
-----------------
* [Introduction](#introduction)
* [How It Works](#how-it-works)
* [Installation](#installation)
* [Basic Usage](#basic-usage)
* [Template Syntax](#template-syntax)
* [Blocks and Variables](#blocks-and-variables)
* [Arithmetic Operations](#arithmetic-operations)
* [Conditional Logic](#conditional-logic)
* [Working with Loops](#working-with-loops)
* [Callback Functions](#callback-functions)
* [Error Handling](#error-handling)
* [Performance Optimization](#performance-optimization)
* [History](#history)
* [License](#license)
Introduction
------------
`XTemplate SE` (Seditio Edition) is a modern and enhanced version of the classic `XTemplate` templating engine for PHP. Designed to separate application logic from presentation, it offers advanced features such as nested blocks, arithmetic operations, conditional logic, loops, and callback functions. It is suitable for both simple and complex projects where flexibility and performance are key.
How It Works
------------
`XTemplate SE` employs an object-oriented model for template processing, setting it apart from the older `XTemplate` class. The concept of this object-oriented approach was inspired by the `Cotemplate` templating engine from the [Cotonti](https://www.cotonti.com/) project, but it has been completely reworked and significantly improved for greater flexibility and performance.
* **Object Structure**:
* Templates are broken down into objects: `XtplBlock` (blocks), `XtplVar` (variables), `XtplExpr` (expressions), `XtplData` (data), and `XtplLogical` (conditions).
* Each template element is represented as a class instance, enabling flexible parsing and rendering, unlike the linear processing of the old `XTemplate`.
* **Expression Handling**:
* Arithmetic and logical operations are processed via `XtplExpr` using Reverse Polish Notation (RPN) for accurate evaluation with proper precedence and parentheses support.
* The old `XTemplate` relied on basic regex-based expression handling with limited functionality.
* **Enhanced Tokenization**:
* Dynamic tokenization supports complex constructs (parentheses, operator precedence), replacing the static approach of the previous version.
* **Advantages Over Old XTemplate**:
* **Extensibility**: Easy to add new operators and functions.
* **Reliability**: Built-in error handling (e.g., division by zero).
* **Performance**: Lazy evaluation of expressions and template structure caching.
Example: `{NUM1 + NUM2}` is converted to RPN (`NUM1 NUM2 +`), evaluated with precedence, and returns the correct result.
Installation
------------
1. Download the `XTemplate.php` file from the repository.
2. Include it in your project:
```
assign('USERNAME', 'John Doe');
$xtpl->parse('MAIN');
$xtpl->out('MAIN');
```
Template `template.tpl`:
```
Hello, {USERNAME}!
```
Output:
```
Hello, John Doe!
```
Template Syntax
---------------
* **Variables**: `{VAR}` — Inserts the value of a variable.
* **Blocks**: ` ... ` — Defines repeatable or conditional sections.
* **Comments**: `` — Ignored during processing.
Blocks and Variables
--------------------
Blocks structure the template, while variables are substituted within them.
Example:
```
Name: {USER.name}
Score: {USER.score}
```
PHP:
```
$xtpl->assign('USER', ['name' => 'Alice', 'score' => 95]);
$xtpl->parse('MAIN');
$xtpl->out('MAIN');
```
Output:
```
Name: Alice
Score: 95
```
Arithmetic Operations
---------------------
Supported operations: `+`, `-`, `*`, `/`, `%`:
```
* Numeric: `{NUM1 + NUM2}`, `{PRICE - DISCOUNT}`
* String: `{STR1 + STR2}` (concatenation)
```
Example:
```
Total: {ITEM.price - ITEM.discount}
```
PHP:
```
$xtpl->assign('ITEM', ['price' => 10, 'discount' => 2]);
```
Output:
```
Total: 8
```
Conditional Logic
-----------------
Use `` for conditions:
```
* Comparison operators: `==`, `===`, `!=`, `!==`, `<`, `>`, `<=`, `>=`
* Logical operators: `AND`, `OR`, `XOR`, `!`
```
Example:
```
High score!
Try harder.
```
PHP:
```
$xtpl->assign('SCORE', 85);
```
Output:
```
High score!
```
Complex conditions with parentheses:
```
Complex condition met
```
Working with Loops
------------------
Use nested blocks or `` loops to iterate over arrays.
### Nested Blocks
Example:
```
- {ITEM.name} - ${ITEM.price}
```
PHP:
```
$xtpl->assign('ITEMS', [
['name' => 'Book', 'price' => 15],
['name' => 'Pen', 'price' => 2]
]);
$xtpl->parse('MAIN.ITEMS');
$xtpl->parse('MAIN');
```
Output:
```
- Book - $15
- Pen - $2
```
### FOR Loops
Use `` to iterate over array values, or `` to access both keys and values.
#### Values Only
Example:
```
Item: {VALUE}
```
PHP:
```
$xtpl->assign('MY_ARRAY', ['Apple', 'Banana', 'Orange']);
$xtpl->parse('MAIN');
```
Output:
```
Item: Apple
Item: Banana
Item: Orange
```
#### Keys and Values
Example:
```
{KEY}: {VALUE}
```
PHP:
```
$xtpl->assign('MY_ARRAY', ['a' => 'Apple', 'b' => 'Banana', 'c' => 'Orange']);
$xtpl->parse('MAIN');
```
Output:
```
a: Apple
b: Banana
c: Orange
```
Callback Functions
------------------
Add modifiers using `|`:
```
* `{VAR|func}` — Applies the function `func` to `VAR`.
* `{VAR|func($this, arg)}` — Passes arguments.
```
Example:
```
Last login: {LAST_LOGIN|strtotime|date('Y-m-d', $this)}
```
PHP:
```
$xtpl->assign('LAST_LOGIN', '2025-03-07 12:00:00');
```
Output:
```
Last login: 2025-03-07
```
Error Handling
--------------
Division by zero (`/`, `%`) returns messages: `"Division by zero"`, `"Modulo by zero"`. Unknown operators throw an `"Unknown operator"` exception.
Example:
```
{NUM / ZERO}
```
Output:
```
Division by zero
```
For comprehensive error handling, add a `try-catch` block in `XtplVar::evaluate()`.
Performance Optimization
------------------------
* **Caching**: Templates are parsed once and stored in memory.
* **Lazy Loading**: Variables are evaluated only when `parse()` is called.
* **Tip**: Minimize nested blocks and complex expressions for large datasets.
History
-------
* **v1.2.0**: Add callback function filtering to XTemplate. Add XTemplate::configure() for global settings initialization
* **v1.1.0**: Fixed `%` operator support and improved error handling.
* **v1.0.0 (2025-03-07)**: Initial release with support for blocks, variables, arithmetic, conditions, and loops.
License
-------
The project is licensed under the [BSD 3-Clause License](LICENSE). You are free to use, modify, and distribute the code provided the license terms are followed.