Download the PHP package dalpras/smart-template without Composer

Smart Template

A small PHP template engine for structured rendering with native PHP arrays, lazy compilation, presets, and named placeholder substitution.

smart-template is designed for projects that want to keep rendering logic in PHP without introducing a separate template language.

Templates are regular PHP arrays made of strings, callbacks, and nested arrays. String leaves are lazily compiled into render closures when accessed.

What it is good at

• Small, reusable HTML fragments and components
• PHP-native template composition
• Dynamic rendering with named placeholders
• Preset-based template registration
• In-memory template collections
• Fine-grained control over escaping and HTML attributes
• Exact custom parameter callbacks
• Call-site token modifiers
• Configurable modifier separator

What it is not

This package is not a full view framework.

It does not try to replace systems built around inheritance, blocks, macros, filters, or expression languages.

It works best when you want explicit PHP control over markup and composition.

Installation

Requirements

• PHP 8.3 or newer

Mental model

A template collection is an array registered under a namespace.

Each entry can be:

• a string with placeholders such as {title} or {rows}
• a closure
• a nested array of more templates
• a lazy template-file reference

When a string leaf is accessed, the engine compiles it lazily into a closure.

Example:

If a placeholder value is itself a closure, the engine resolves it before substitution.

Quick start

1) Create a preset

2) Register the preset

3) Render it

Output:

Presets

A preset is a class that registers templates into the engine.

Presets replace automatic filesystem loading. The engine does not scan directories or resolve template names from the filesystem.

Then render the registered collection:

The first registered collection automatically becomes the default collection.

You can also mark a collection as default explicitly:

PresetInterface

Presets can implement PresetInterface.

Usage:

Register it under a custom namespace:

Then render it explicitly:

Application UI preset example

An application preset can register the built-in HTML preset and merge application templates into the same namespace.

Usage:

Loading templates from PHP files

The engine provides require() as a low-level helper for presets.

This is explicit loading, not filesystem discovery.

Example template file:

Registering and extending templates

Use register() to create a namespace or merge templates into an existing namespace.

Create a namespace:

Merge more templates into the same namespace:

Override an existing template:

Result:

The rule is:

addCustom() may remain as a backward-compatible alias, but new code should use register().

Default collection

The first registered namespace becomes the default collection.

Set the default namespace manually:

Access it explicitly:

Nested templates

Nested arrays are wrapped into RenderCollection objects.

Lazy template files

A template file can reference another file lazily.

partials.php:

The lazy file is loaded only when that branch is accessed.

Lazy placeholder closures

A placeholder value can be a closure.

Placeholder closures receive:

1. the root RenderCollection
2. the current scoped RenderCollection
3. the TemplateEngine
4. the current namespace

Rendering attributes

The engine includes an attributes() helper.

Example output:

Notes:

• id values are normalized into an HTML-friendly form
• id, title, name, and alt can be escaped through configured helpers
• closures are supported as attribute values

Custom parameter callbacks

You can register callbacks that transform or provide exact token values before final substitution.

A common use case is rendering HTML attributes from an array.

Then templates can use {attributes} consistently:

Custom parameter callbacks are matched by exact token name.

Call-site token modifiers

Call-site token modifiers let the caller transform a value while keeping the template unchanged.

The modifier is written in the argument key, not inside the template.

Template:

Register a modifier:

Usage:

Output:

Internally, this:

is resolved before rendering as:

The template still contains only:

Chained modifiers

Modifiers can be chained.

Output:

Modifiers run before parameter callbacks

Modifiers are resolved before custom parameter callbacks.

This is useful when a modifier prepares structured data that a callback will later render.

Template:

Usage:

Output:

Custom token styles

Smart Template does not require {...} tokens.

The token used in the caller only has to match the token used in the template.

For example, this template:

can be rendered with:

The engine resolves %content%|upperCase into %content%, then replaces %content% in the template.

These token styles are all valid:

The base token must not contain the configured modifier separator.

Configurable modifier separator

The default modifier separator is:

So this works by default:

You can choose a different separator:

Then use it in call-site arguments:

Chaining also uses the configured separator:

Choose a separator that does not appear inside your tokens or modifier names.

Cross-collection composition

Collections can compose other registered collections by using the same engine instance.

Return values and stringification

When placeholders are substituted, the engine converts values to strings.

Common cases are handled:

• strings
• integers and floats
• booleans
• null
• DateTimeInterface
• enums
• Stringable
• arrays and objects through JSON-style encoding

Example:

For HTML output, escaping is still your application's responsibility.

Recommended usage pattern

A reliable way to use this package is:

1. Register templates through presets.
2. Use semantic namespaces such as html, ui, or mail.
3. Use register() again to merge into or override an existing namespace.
4. Keep template strings focused on markup.
5. Use named tokens consistently.
6. Use call-site token modifiers for caller-side transformations.
7. Escape untrusted content at the application boundary.
8. Reuse a TemplateEngine instance instead of creating one per render.

Error handling

collection() throws when the namespace is not registered.

require() throws when the explicit file path does not exist.

Template files used by presets should return arrays.

Example project structure

src/Template/UiPreset.php:

src/templates/default.php:

src/templates/partials.php:

Security notes

This package gives you control, but it does not automatically make HTML safe.

Be careful with:

• user-controlled HTML
• attribute values
• URLs
• inline JavaScript
• mixed trusted and untrusted content

Treat output escaping as an application concern.

Use your escaper/helpers consistently when rendering untrusted data.

When to choose this package

Choose Smart Template when:

• you want a small PHP-native renderer
• you prefer arrays and closures over a custom template language
• you are rendering many small reusable fragments
• you want explicit control over composition
• you want preset-based template registration
• you want caller-side transformations without template-side expressions

Consider a larger templating system when:

• your team wants strict separation between PHP and views
• you need inheritance, blocks, macros, filters, or expression languages
• you want a larger ecosystem of integrations and tooling

Minimal reference

TemplateEngine

Main methods:

PresetInterface

RenderCollection

Collections behave like nested arrays with lazy wrapping and lazy compilation.

Migration from filesystem loading

Previous versions allowed filesystem-oriented usage like:

The new model is preset-based:

Or explicitly:

The engine no longer scans template directories or resolves template files by name.

Files are loaded only when a preset explicitly calls require().

Avoid using filenames as namespaces:

License

See the package metadata in composer.json / Packagist and keep the README aligned with that metadata.