Templating

Last updated: 2026-10-30

Canvas supports multiple templating engines through optional packages. Smarty is installed by default, but you can switch to Blade, Twig, Latte, or Plates depending on your preference — or use multiple engines side by side within the same application.

explanation

Installation

Each templating engine is available as a separate Composer package. After installing, run the engine's init command to generate the config file:

composer require quellabs/canvas-smarty
php vendor/bin/sculpt smarty:init

Replace smarty with the identifier of the engine you are installing. The identifier is also the string that activates it as the default in config/app.php:

IdentifierPackageEngine
smartyquellabs/canvas-smartySmarty (default, installed with Canvas)
bladequellabs/canvas-bladeLaravel Blade syntax
twigquellabs/canvas-twigTwig by Symfony
lattequellabs/canvas-latteLatte by Nette
platesquellabs/canvas-platesPlates (native PHP templates)
handlebarsquellabs/canvas-handlebarsHandlebars (compiled native PHP templates)

Basic Usage

Call $this->render() from any controller that extends BaseController, passing the template path and an array of variables:

class UserController extends BaseController {

    /**
     * @Route("/users")
     */
    public function index(): Response {
        $users = $this->em()->findBy(UserEntity::class, ['active' => true]);
        return $this->render('users/index.tpl', ['users' => $users]);
    }
}

Template paths are relative to the template_dir defined in the engine's config file (see Engine-Specific Configuration below). The default is the templates/ directory in your project root.

{* templates/users/index.tpl *}
{foreach $users as $user}
    <p>{$user->getName()}</p>
{/foreach}

Template inheritance, layouts, and partials are handled entirely by the engine itself — refer to the engine's own documentation for those features.

Configuration

Set the active templating engine in config/app.php using the template_engine key. The value must match the package name of the installed engine:

// Template engine
'template_engine' => 'smarty',  // default

Engine-Specific Configuration

Each templating engine can be configured individually through its own config file in the config/ directory. Run the engine's init command to generate it:

CommandDescription
sculpt smarty:initPublish config/smarty.php
sculpt blade:initPublish config/blade.php
sculpt twig:initPublish config/twig.php
sculpt latte:initPublish config/latte.php
sculpt plates:initPublish config/plates.php
sculpt handlebars:initPublish config/handlebars.php

Use these files to configure engine-specific options such as the template directory, caching, debug mode, and extensions.

Rendering via the Container

$this->render() is a convenience wrapper around the DI-resolved engine. Resolving the engine directly from the container is equivalent and produces the same result:

// Via BaseController shorthand
return $this->render('users/index.tpl', ['users' => $users]);

// Via container directly — identical result
$engine = $this->container->get(TemplateEngineInterface::class);
return new Response($engine->render('users/index.tpl', ['users' => $users]));

The container approach is useful in service classes or other contexts where BaseController is not available.

Injecting an Engine into a Route Method

A specific engine can be injected directly into a route method using @WithContext. This is useful when a single route needs a different engine than the application default:

/**
 * @Route("/users")
 * @WithContext(parameter="engine", context="blade")
 */
public function index(TemplateEngineInterface $engine): Response {
    $users = $this->em()->findBy(UserEntity::class, ['active' => true]);
    return new Response($engine->render('users/index.blade.php', ['users' => $users]));
}

Without @WithContext, the default engine is injected automatically. Use @WithContext only when you need a specific engine other than the default — the context value must match one of the engine identifiers listed above. See Contextual Containers for full details on @WithContext.

Mixing Engines via Dependency Injection

Canvas allows you to use multiple templating engines within the same application. Resolve a specific engine from the container using the for() method with the engine identifier:

$template = $container->for('smarty')->get(TemplateEngineInterface::class);
$template = $container->for('plates')->get(TemplateEngineInterface::class);
$template = $container->for('blade')->get(TemplateEngineInterface::class);

This is useful when migrating between engines incrementally, or when different parts of your application have different templating needs. Each resolved instance is fully configured and ready to render.

Engine Documentation

For template syntax, layouts, inheritance, and engine-specific features, refer to each engine's own documentation:

Frequently Asked Questions

Am I required to use Smarty?

No. Smarty is installed and active by default, but it's one of several interchangeable options. Install the package for the engine you want (Blade, Twig, Latte, Plates, or Handlebars) and set template_engine in config/app.php to its identifier to make it the default instead.

Can I use more than one templating engine in the same application?

Yes. Resolve a specific engine from the container with $container->for('plates')->get(TemplateEngineInterface::class) (or the equivalent for any installed engine), independently of whatever template_engine is set as the app-wide default. This is useful when migrating between engines incrementally.

How do I use a different engine for just one route, without changing the app-wide default?

Add @WithContext(parameter="engine", context="blade") (or any other installed engine's identifier) to the route method and type-hint TemplateEngineInterface on the matching parameter. Routes without the annotation keep injecting the default engine.

Does $this->render() behave differently from resolving the engine from the container directly?

No — it's a convenience wrapper around the same DI-resolved TemplateEngineInterface, and produces an identical result. Resolving the engine directly from the container is the way to render templates from service classes or other code where BaseController isn't available.

Does Canvas provide its own template inheritance or layout system?

No — template inheritance, layouts, and partials are handled entirely by whichever engine you're using, through that engine's own syntax and conventions. Canvas's role is resolving and rendering the configured engine; features like layouts are documented on each engine's own site.

Where are template paths resolved from?

Relative to the template_dir set in the active engine's own config file (config/smarty.php, config/blade.php, etc.), generated by that engine's sculpt ...:init command. The default is the templates/ directory at the project root.