quellabs/canvas-handlebars

Handlebars template engine integration for the Canvas PHP framework via LightnCandy, with contextual containers and automatic service discovery

1.0.0 2026-03-26 12:50 UTC

Requires

• quellabs/contracts: ^1.
• quellabs/dependency-injection: ^1.
• quellabs/sculpt: ^1.
• quellabs/signal-hub: ^1.
• quellabs/support: ^1.
• zordius/lightncandy: ^1.2

MIT

• Quellabs

• handlebars
• lightncandy
• canvas-framework
• template-integration
• php-templating

README

A Handlebars template engine integration for the Canvas PHP framework, powered by LightnCandy.

Installation

composer require quellabs/canvas-handlebars

Requirements

• PHP 8.3 or higher
• Canvas framework

How it works

Unlike output-cache engines (Smarty, Twig), LightnCandy compiles Handlebars templates to native PHP closures. The compiled files are stored in compile_dir and reused across requests. Recompilation only happens when a source template is newer than its compiled counterpart — no opcode cache invalidation overhead.

Usage

The Handlebars template engine is automatically registered with Canvas through the service discovery system.

class HomeController {
    public function index(TemplateEngineInterface $handlebars) {
        return $handlebars->render('home.hbs', [
            'title' => 'Welcome to Canvas',
            'user'  => $user
        ]);
    }
}

Template Files

templates/
├── home.hbs
├── layouts/
│   └── app.hbs
└── partials/
    └── header.hbs

Helpers

Register helpers in config/handlebars.php:

'helpers' => [
    'uppercase'  => fn($str)  => strtoupper($str),
    'formatDate' => fn($ts)   => date('Y-m-d', $ts),
],

Or register them at runtime via the engine instance:

$handlebars->registerHelper('uppercase', fn($str) => strtoupper($str));

Use in templates:

<h1>{{uppercase title}}</h1>
<p>Published: {{formatDate createdAt}}</p>

Partials

Partials are reusable template fragments. Register them as strings in config or at runtime:

$handlebars->registerPartial('header', '<header>{{siteName}}</header>');

Use in templates:

{{> header}}
<main>{{content}}</main>

Configuration

Key	Default	Description
template_dir	templates/	Where .hbs files are stored
compile_dir	storage/handlebars/compile/	Where compiled PHP renderers are cached
strict_mode	false	Throw on missing variables instead of rendering empty
standalone	false	Embed helpers in compiled output (no runtime dependency)
helpers	[]	Named helper callables
partials	[]	Named partial template strings
globals	[]	Variables available in all templates

Sculpt Commands

php sculpt handlebars:clear-cache

Removes all compiled PHP renderers, forcing recompilation on the next request.

License

MIT License