Stempler

https://github.com/spiral/stempler
Admin
Stempler is an HTML markup processor and template engine framework for the Spiral PHP framework.
Tokens:5,066
Snippets:36
Trust Score:10
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Create Custom Directive with `AbstractDirective`

Source: https://context7.com/spiral/stempler/llms.txt

Extend `AbstractDirective` to create custom directives. Methods named `render<DirectiveName>` will be invoked for corresponding `@directive` calls in templates. This example shows how to create `@asset` and `@vite` directives, registering them with `DynamicToPHP`.

```php
use Spiral\Stempler\Directive\AbstractDirective;
use Spiral\Stempler\Node\Dynamic\Directive;

final class AssetDirective extends AbstractDirective
{
    // renders @asset('path/to/file.css')
    public function renderAsset(Directive $directive): string
    {
        $path = trim($directive->body, "'\"");
        return sprintf('<?php echo asset(%s); ?>', var_export($path, true));
    }

    // renders @vite('resources/app.js')
    public function renderVite(Directive $directive): string
    {
        return sprintf('<?php echo vite(%s); ?>', $directive->body);
    }
}

// Register with DynamicToPHP finalizer
$dynamic = new \Spiral\Stempler\Transform\Finalizer\DynamicToPHP();
$dynamic->addDirective(new AssetDirective());
$builder->addVisitor($dynamic, Builder::STAGE_FINALIZE);

// Template:
// @asset('css/app.css')   → <?php echo asset('css/app.css'); ?>
// @vite('resources/app.js') → <?php echo vite('resources/app.js'); ?>
```

--------------------------------

### Conditional and Loop Directives (`@if`, `@foreach`)

Source: https://context7.com/spiral/stempler/llms.txt

Utilize built-in directives like `@foreach`, `@if`, `@elseif`, and `@else` to render standard PHP control structures. These directives are processed by `ConditionalDirective` and `LoopDirective` and should be registered via `DynamicToPHP` at `STAGE_FINALIZE`. The example also includes a `@json` directive.

```php
use Spiral\Stempler\Loader\StringLoader;

$loader = new StringLoader();
$loader->set('list', '
@foreach($items as $item)
    @if($item["active"])
        <li class="active">{{ $item["label"] }}</li>
    @elseif($item["hidden"])
        {{-- hidden item, skip --}}
    @else
        <li>{{ $item["label"] }}</li>
    @endif
@endforeach

@json($config)
');

// Compiled to standard PHP foreach / if / endif blocks + json_encode
$result = $builder->compile('list');
echo $result->getContent();
```

--------------------------------

### Dynamic and Raw Output with `{{ }}` and `{!! !!}`

Source: https://context7.com/spiral/stempler/llms.txt

Control output escaping using `{{ $expr }}` for context-aware XSS-escaped output (defaults to `htmlspecialchars`) and `{!! $expr !!}` for raw, unescaped output. The example shows both in HTML paragraphs and within a `<script>` tag, where `{{ }}` automatically uses `json_encode`.

```php
use Spiral\Stempler\Loader\StringLoader;

$loader = new StringLoader();
$loader->set('view', '
<p>Escaped:   {{ $userInput }}</p>
<p>Raw HTML:  {!! $trustedHtml !!}</p>
<script>var data = {{ $jsonData }};</script>
');

// Compiled output:
// <p>Escaped:  <?php echo htmlspecialchars((string)($userInput), ENT_QUOTES|ENT_SUBSTITUTE, 'utf-8'); ?></p>
// <p>Raw HTML: <?php echo $trustedHtml; ?></p>
// <script>var data = <?php echo json_encode($jsonData, JSON_HEX_TAG|...); ?>;</script>
// Note: {{ }} inside <script> automatically uses json_encode instead of htmlspecialchars

$result = $builder->compile('view');
echo $result->getContent();
```

--------------------------------

### Define Reusable Component Inline with `use:inline`

Source: https://context7.com/spiral/stempler/llms.txt

Use `use:inline` to define a component directly within the current template. This is suitable for small, locally scoped components. The example demonstrates setting a component named 'icon' using `StringLoader` and then compiling a template that uses this inline component.

```php
use Spiral\Stempler\Loader\StringLoader;

$loader = new StringLoader();
$loader->set('page', '
<use:inline name="icon">
    <svg class="icon icon-${name}" aria-hidden="true">
        <use xlink:href="#icon-${name}"></use>
    </svg>
</use:inline>

<icon name="home"/>
<icon name="settings"/>
');

$result = $builder->compile('page');
// <svg class="icon icon-home" ...>...</svg>
// <svg class="icon icon-settings" ...>...</svg>
echo $result->getContent();
```

--------------------------------

### Directory Import with `use:dir`

Source: https://context7.com/spiral/stempler/llms.txt

Map all templates within a directory to a tag namespace using `use:dir`. This allows importing entire component libraries with a specified prefix. Templates within the directory are accessed using the namespace followed by the template name.

```php
use Spiral\Stempler\Loader\StringLoader;

$loader = new StringLoader();
$loader->set('ui/button', '<button type="${type|button}" class="btn ${class}"><block:context/></button>');
$loader->set('ui/card',   '<div class="card ${class}"><block:context/></div>');

$loader->set('page', '
<use:dir dir="ui" ns="ui"/>

<ui:button type="submit" class="primary">Save</ui:button>
<ui:card class="shadow">
    <p>Card content here.</p>
</ui:card>
');

$result = $builder->compile('page');
// <button type="submit" class="btn primary">Save</button>
// <div class="card shadow"><p>Card content here.</p></div>
echo $result->getContent();
```

--------------------------------

### Load Templates from Filesystem using DirectoryLoader

Source: https://context7.com/spiral/stempler/llms.txt

Instantiate DirectoryLoader to resolve template paths relative to a base directory with a configurable extension. The load() method returns a Source object containing the template content and its absolute filesystem path.

```php
use Spiral\Stempler\Loader\DirectoryLoader;
use Spiral\Stempler\Exception\LoaderException;

$loader = new DirectoryLoader(
    directory: __DIR__ . '/resources/views',
    extension: '.dark.php',          // default
);

// load() returns a Loader\Source with content + real filename
try {
    $source = $loader->load('layout/base');
    // resolves to __DIR__ . '/resources/views/layout/base.dark.php'
    echo $source->getContent();      // raw template string
    echo $source->getFilename();     // absolute filesystem path (used in error messages)
} catch (LoaderException $e) {
    echo "Not found: " . $e->getMessage();
}
```

--------------------------------

### Compile Template from Path using Builder

Source: https://context7.com/spiral/stempler/llms.txt

Use the Builder class to orchestrate template loading, parsing, transformation, and compilation. Register grammars, syntaxes, renderers, and visitors to customize the processing pipeline. Handles template resolution and error reporting.

```php
use Spiral\Stempler\Builder;
use Spiral\Stempler\Compiler\Renderer\{CoreRenderer, DynamicRenderer, HTMLRenderer, PHPRenderer};
use Spiral\Stempler\Directive\{ConditionalDirective, DirectiveGroup, JsonDirective, LoopDirective, PHPDirective};
use Spiral\Stempler\Lexer\Grammar\{DynamicGrammar, HTMLGrammar, InlineGrammar, PHPGrammar};
use Spiral\Stempler\Loader\DirectoryLoader;
use Spiral\Stempler\Parser\Syntax\{DynamicSyntax, HTMLSyntax, InlineSyntax, PHPSyntax};
use Spiral\Stempler\Transform\Finalizer\DynamicToPHP;
use Spiral\Stempler\Transform\Merge\{ExtendsParent, ResolveImports};
use Spiral\Stempler\Transform\Visitor\{DefineAttributes, DefineBlocks};

// Load templates from a directory; default extension is .dark.php
$loader = new DirectoryLoader('/path/to/templates', '.dark.php');

$builder = new Builder($loader);

// Register grammars + syntaxes (order matters)
$builder->getParser()->addSyntax(new PHPGrammar(),     new PHPSyntax());
$builder->getParser()->addSyntax(new InlineGrammar(),  new InlineSyntax());
$builder->getParser()->addSyntax(new DynamicGrammar(), new DynamicSyntax());
$builder->getParser()->addSyntax(new HTMLGrammar(),    new HTMLSyntax());

// Register compilers renderers
$directives = new DirectiveGroup();
$directives->addDirective(new ConditionalDirective());
$directives->addDirective(new LoopDirective());
$directives->addDirective(new JsonDirective());
$directives->addDirective(new PHPDirective());

$builder->getCompiler()->addRenderer(new CoreRenderer());
$builder->getCompiler()->addRenderer(new PHPRenderer());
$builder->getCompiler()->addRenderer(new DynamicRenderer($directives));
$builder->getCompiler()->addRenderer(new HTMLRenderer());

// Register AST visitors
$builder->addVisitor(new DefineAttributes(), Builder::STAGE_PREPARE);
$builder->addVisitor(new DefineBlocks(),     Builder::STAGE_PREPARE);
$builder->addVisitor(new ResolveImports($builder), Builder::STAGE_TRANSFORM);
$builder->addVisitor(new ExtendsParent($builder),  Builder::STAGE_TRANSFORM);

$dynamic = new DynamicToPHP();
$dynamic->addDirective(new LoopDirective());
$dynamic->addDirective(new ConditionalDirective());
$builder->addVisitor($dynamic, Builder::STAGE_FINALIZE);

// Compile a template and get generated PHP source
try {
    $result = $builder->compile('home/index');   // resolves to /path/to/templates/home/index.dark.php
    echo $result->getContent();                  // string of compiled PHP
} catch (
Spiral\Stempler\Exception\LoaderException $e) {
    echo "Template not found: " . $e->getMessage();
} catch (
Spiral\Stempler\Exception\CompilerException $e) {
    echo "Compile error at {" . $e->getFile() . ":" . $e->getLine() . " — " . $e->getMessage();
}
```

--------------------------------

### Bundle Import with `use:bundle`

Source: https://context7.com/spiral/stempler/llms.txt

Import a bundle of components using `use:bundle`. The specified bundle template itself contains `use:element` or `use:inline` declarations. This enables grouping library components under an optional namespace prefix.

```php
use Spiral\Stempler\Loader\StringLoader;

$loader = new StringLoader();

// Bundle manifest — aggregates multiple components
$loader->set('mylib/bundle', '
<use:element path="mylib/alert"  as="alert"/>
<use:element path="mylib/badge"  as="badge"/>
');
$loader->set('mylib/alert', '<div class="alert alert-${type|info}"><block:context/></div>');
$loader->set('mylib/badge', '<span class="badge badge-${color|primary}"><block:context/></span>');

// Consumer: import the whole bundle under namespace "lib"
$loader->set('page', '
<use:bundle path="mylib/bundle" ns="lib"/>

<lib:alert type="danger">Something went wrong!</lib:alert>
<lib:badge color="success">New</lib:badge>
');

$result = $builder->compile('page');
// <div class="alert alert-danger">Something went wrong!</div>
// <span class="badge badge-success">New</span>
echo $result->getContent();
```

--------------------------------

### Component Import with `use:element`

Source: https://context7.com/spiral/stempler/llms.txt

Register a single template file as a reusable HTML component using `use:element`. Components can utilize `<block:name>` slots and `${attr}` attribute placeholders. The `as` attribute defines the tag name for the component.

```php
use Spiral\Stempler\Loader\StringLoader;

$loader = new StringLoader();

// Component template: uses ${href} attribute and a content block
$loader->set('components/link', '<a href="${href}" class="${class|btn}"><block:context/></a>');

// Page: imports the component and uses it
$loader->set('page', '
<use:element path="components/link" as="app-link"/>

<app-link href="/home" class="nav-link">Home</app-link>
<app-link href="/about">About</app-link>
');

$result = $builder->compile('page');
// Output:
// <a href="/home" class="nav-link">Home</a>
// <a href="/about" class="btn">About</a>   ← falls back to default class "btn"
echo $result->getContent();
```

--------------------------------

### Template Inheritance with `<extends>`

Source: https://context7.com/spiral/stempler/llms.txt

Implement template inheritance by extending a parent template using `<extends:path/>` or `<extends path="path"/>`. Child templates can override named blocks defined in the parent. Ensure the `ExtendsParent` visitor is registered at `STAGE_TRANSFORM`.

```php
use Spiral\Stempler\Loader\StringLoader;

$loader = new StringLoader();

// Parent template: defines layout with overridable blocks
$loader->set('layout', '
<html>
<head><title><block:title>Default Title</block:title></title></head>
<body class="${bodyClass|default}">
    <block:content>No content</block:content>
</body>
</html>
');

// Child template: extends parent and fills blocks
$loader->set('page', '
<extends:layout bodyClass="main"/>
<block:title>My Page</block:title>
<block:content>
    <p>Hello, ${parent} is the parent content.</p>
</block:content>
');

$result = $builder->compile('page');
// Produces the parent HTML with child blocks injected;
// ${parent} expands to "No content" (parent block default value)
// bodyClass attribute is forwarded to the layout tag
echo $result->getContent();
```

--------------------------------

### Load Templates from Strings with StringLoader

Source: https://context7.com/spiral/stempler/llms.txt

Use StringLoader to store templates as named strings in memory. This is useful for testing or when templates are generated dynamically. Pass the loader to the Builder.

```php
use Spiral\Stempler\Loader\StringLoader;

$loader = new StringLoader();
$loader->set('greeting', '<h1>Hello, {{ $name }}!</h1>');
$loader->set('page',     '<extends:greeting/><block:name>World</block:name>');

// Pass to Builder as usual
$builder = new Builder($loader);
// ... add grammars, renderers, visitors ...

$result = $builder->compile('greeting');
// $result->getContent() => '<h1>Hello, <?php echo htmlspecialchars(..., $name, ...); ?>!</h1>'
```

--------------------------------

### Implement VisitorInterface for AST Traversal

Source: https://context7.com/spiral/stempler/llms.txt

Implement VisitorInterface to intercept and modify AST nodes during compilation. Use return values like REMOVE_NODE or DONT_TRAVERSE_CHILDREN to control traversal.

```php
use Spiral\Stempler\VisitorInterface;
use Spiral\Stempler\VisitorContext;
use Spiral\Stempler\Node\HTML\Tag;
use Spiral\Stempler\Node\Raw;

final class StripCommentTagsVisitor implements VisitorInterface
{
    public function enterNode(mixed $node, VisitorContext $ctx): mixed
    {
        // Skip traversal into any <comment> tag entirely
        if ($node instanceof Tag && $node->name === 'comment') {
            return self::DONT_TRAVERSE_CURRENT_AND_CHILDREN;
        }
        return null;
    }

    public function leaveNode(mixed $node, VisitorContext $ctx): mixed
    {
        // Remove the <comment> tag from the output
        if ($node instanceof Tag && $node->name === 'comment') {
            return self::REMOVE_NODE;
        }
        return null;
    }
}

// Register at the prepare stage so it runs before transforms
$builder->addVisitor(new StripCommentTagsVisitor(), Builder::STAGE_PREPARE);
```

--------------------------------

### Access Compiled Output and Source Maps

Source: https://context7.com/spiral/stempler/llms.txt

Retrieve the generated PHP source code and build source maps for debugging. Source maps enable line-level mapping from generated PHP back to original template files.

```php
use Spiral\Stempler\Loader\DirectoryLoader;

$loader = new DirectoryLoader('/templates');
$result = $builder->compile('pages/contact');

// Get the generated PHP source
$phpSource = $result->getContent();

// Get all template paths that contributed to this output
$paths = $result->getPaths();  // e.g. ['pages/contact', 'layout/base', 'ui/form']

// Build a source map for error tracing
$sourceMap = $result->getSourceMap($loader);

// Given a line number in the generated PHP, find the original template location(s)
$stack = $sourceMap->getStack(42);
foreach ($stack as $frame) {
    echo "{$frame['file']} line {$frame['line']}\n";
    // e.g. /templates/ui/form.dark.php line 7
    //      /templates/pages/contact.dark.php line 15
}

// Serialize/deserialize for caching
$serialized = $sourceMap->serialize();          // JSON string
file_put_contents('/cache/contact.map', $serialized);

$restored = new \Spiral\Stempler\Compiler\SourceMap();
$restored->unserialize(file_get_contents('/cache/contact.map'));
$restoredStack = $restored->getStack(42);
```

--------------------------------

### Implement Custom LoaderInterface for Template Sources

Source: https://context7.com/spiral/stempler/llms.txt

Implement LoaderInterface to load templates from custom sources like databases or remote storage. The load method should return a Source object containing the template content and an optional filename.

```php
use Spiral\Stempler\Loader\LoaderInterface;
use Spiral\Stempler\Loader\Source;
use Spiral\Stempler\Exception\LoaderException;

final class DatabaseLoader implements LoaderInterface
{
    public function __construct(private \PDO $pdo) {}

    public function load(string $path): Source
    {
        $stmt = $this->pdo->prepare('SELECT content, updated_at FROM templates WHERE name = ?');
        $stmt->execute([$path]);
        $row = $stmt->fetch(\PDO::FETCH_ASSOC);

        if (!$row) {
            throw new LoaderException(sprintf('Template "%s" not found in database', $path));
        }

        // Source(content, filename) — filename is optional, used for error messages / source maps
        return new Source($row['content'], "db://{$path}");
    }
}

// Usage
$loader  = new DatabaseLoader($pdo);
$builder = new Builder($loader);
// ... register grammars and renderers ...
$result  = $builder->compile('emails/welcome');
```

--------------------------------

### Aggregate Pass-Through Attributes with `attr:aggregate`

Source: https://context7.com/spiral/stempler/llms.txt

Use `attr:aggregate` on a component's root element to automatically absorb and inject any extra attributes passed by the caller. This is useful for components that need to accept arbitrary HTML attributes like `placeholder` or `required` without explicitly defining them.

```php
use Spiral\Stempler\Loader\StringLoader;

$loader = new StringLoader();

// Component that accepts any extra attributes on its root element
$loader->set('ui/input',
    '<input type="${type|text}" name="${name}" attr:aggregate/>'
);

$loader->set('page', '
<use:element path="ui/input" as="app-input"/>

<app-input name="email" type="email" placeholder="Enter email" required/>
');

// Output: <input type="email" name="email" placeholder="Enter email" required/>
// attr:aggregate absorbed placeholder and required automatically
$result = $builder->compile('page');
echo $result->getContent();
```
Tokens:
Raw