Sugar Templates

Appearance

Getting Started ​

Get a working Sugar setup in minutes, then grow into loaders, caching, and custom compilation as your app evolves.

INFO

Sugar compiles templates to plain PHP and caches the result for fast rendering.

Installation ​

bash
composer require josbeir/sugar
bash
composer require josbeir/sugar --dev

Basic Usage ​

The high-level Engine API provides caching, template loading, and context binding out of the box:

php
use Sugar\Engine;
use Sugar\Loader\FileTemplateLoader;
use Sugar\Cache\FileCache;
use Sugar\Config\SugarConfig;

$engine = Engine::builder()
    ->withTemplateLoader(new FileTemplateLoader(
        config: new SugarConfig(),
        templatePaths: __DIR__ . '/templates',
        componentPaths: 'components'
    ))
    ->withCache(new FileCache(__DIR__ . '/cache'))
    ->withDebug(true)
    ->build();

echo $engine->render('pages/home', [
    'title' => 'Welcome',
    'user' => $currentUser,
]);

TIP

By default, FileTemplateLoader resolves s:extends and s:include paths relative to the current template. If you prefer absolute-only lookups, pass absolutePathsOnly: true and use root-style paths like layouts/base.sugar.php.

Example Template ​

html
<h1 s:text="$title"></h1>

<s-card s:bind="$userCard">
    <div s:slot="header">Welcome back</div>
    <p>Hello, <?= $user->name ?></p>
</s-card>
php
echo $engine->render('pages/home', [
    'title' => 'Welcome',
    'user' => $currentUser,
    'userCard' => ['class' => 'card'],
]);

Low-Level Compiler API ​

For advanced use cases where you need direct control over compilation:

php
use Sugar\Compiler;
use Sugar\Parser\Parser;
use Sugar\Escape\Escaper;
use Sugar\Loader\FileTemplateLoader;
use Sugar\Config\SugarConfig;

$loader = new FileTemplateLoader(
    config: new SugarConfig(),
    templatePaths: __DIR__ . '/templates'
);

$compiler = new Compiler(
    new Parser(new SugarConfig()),
    new Escaper(),
    templateLoader: $loader
);

$compiled = $compiler->compile('<div s:if="$show"><?= $message ?></div>');
Details

When to use the compiler directly

  • Pre-compiling templates for a build step
  • Integrating Sugar into a custom framework
  • Advanced caching or storage strategies

Requirements ​

  • PHP 8.2+ (tested on 8.2, 8.3, 8.4, 8.5)
  • Composer

The pipe syntax (|>) is a compile-time feature, so you can use PHP 8.5 syntax even on PHP 8.2.