README

This project provides a composer package with a Twig loader for files with YAML front-matter.

Installation

Run

composer require ergebnis/twig-front-matter

Usage

Loading Twig templates with the FrontMatterLoader

This project ships with a FrontMatterLoader that you can use to load Twig templates with YAML front-matter.

The FrontMatterLoader

• parses a Twig template and separates the front-matter from the body-matter using `ergebnis/front-matter
• converts the front-matter data to Twig assignments using an implementation of Converter\FrontMatterConverter
• returns a new Twig Source that merges the Twig assignments from the front-matter data with the body-matter from the Twig template

YAML front-matter

Assume that you have a Twig template with the following YAML front-matter:

foo: bar
number: 1234
pi: 3.14159
date: 2016-05-27
empty: ~
invalid-key: "hmm"
multiline: |
  Multiple
  Line
  String
object:
  key: value
  datetime: 2020-11-12 12:54:12
  values:
    - one
    - two

Converting YAML front-matter to Twig assignments with the Converter/ToMultipleAssignmentsFrontMatterConverter

This project ships with a Converter/ToMultipleAssignmentsFrontMatterConverter.php that you can use to convert the YAML front-matter to multiple Twig assignments.

The example below will convert the parsed YAML front-matter data to multiple Twig assignments that will assign data to Twig variables with force:

declare(strict_types=1);

use Ergebnis\Twig;

$frontMatterConverter = new Twig\FrontMatter\Converter\ToMultipleAssignmentsFrontMatterConverter(true);

echo $frontMatterConverter->convert($data);

{% set foo = "bar" %}
{% set number = 1234 %}
{% set pi = 3.14159 %}
{% set date = (1464307200|date_modify('0sec')) %}
{% set empty = null %}
{% set multiline = "Multiple\nLine\nString\n" %}
{% set object = { key: "value", datetime: (1605185652|date_modify('0sec')), values: { 0: "one", 1: "two" } } %}

The example below will convert the parsed YAML front-matter data to multiple Twig assignments that will assign data to Twig variables without force (taking into account that you may pass variables to the template and prefer not to override these variables with front-matter):

declare(strict_types=1);

use Ergebnis\Twig;

$frontMatterConverter = new Twig\FrontMatter\Converter\ToMultipleAssignmentsFrontMatterConverter(false);

echo $frontMatterConverter->convert($data);

{% set foo = foo is defined ? foo : "bar" %}
{% set number = number is defined ? number : 1234 %}
{% set pi = pi is defined ? pi : 3.14159 %}
{% set date = date is defined ? date : (1464307200|date_modify('0sec')) %}
{% set empty = empty is defined ? empty : null %}
{% set multiline = multiline is defined ? multiline : "Multiple\nLine\nString\n" %}
{% set object = object is defined ? object|merge({ key: "value", datetime: (1605185652|date_modify('0sec')), values: { 0: "one", 1: "two" } }) : { key: "value", datetime: (1605185652|date_modify('0sec')), values: { 0: "one", 1: "two" } } %}

Converting YAML front-matter to a Twig assignment with the Converter/ToSingleAssignmentFrontMatterConverter

This project ships with a Converter/ToSingleAssignmentFrontMatterConverter.php that you can use to convert the YAML front-matter to a single Twig assignment.

The example below will convert the parsed YAML front-matter data to a single Twig assignment that will assign data to a Twig variable with force:

declare(strict_types=1);

use Ergebnis\Twig;

$frontMatterConverter = new Twig\FrontMatter\Converter\ToSingleAssignmentFrontMatterConverter(
    Twig\Expression\Name::fromString('data'),
    false,
);

echo $frontMatterConverter->convert($data);

{% set data = { foo: "bar", number: 1234, pi: 3.14159, date: (1464307200|date_modify('0sec')), empty: null, invalid-key: "hmm", multiline: "Multiple\\nLine\\nString\\n", object: { key: "value", datetime: (1605185652|date_modify('0sec')), values: { 0: "one", 1: "two" } } } %}

The example below will convert the parsed YAML front-matter data to a single Twig assignment that will assign data to a Twig variables without force (taking into account that you may pass a variable to the template and prefer not to override this variable with front-matter):

declare(strict_types=1);

use Ergebnis\Twig;

$frontMatterConverter = new Twig\FrontMatter\Converter\ToSingleAssignmentFrontMatterConverter(
    Twig\Expression\Name::fromString('data'),
    false,
);

echo $frontMatterConverter->convert($data);

{% set data = data is defined ? data|merge({ foo: "bar", number: 1234, pi: 3.14159, date: (1464307200|date_modify('0sec')), empty: null, invalid-key: "hmm", multiline: "Multiple\\nLine\\nString\\n", object: { key: "value", datetime: (1605185652|date_modify('0sec')), values: { 0: "one", 1: "two" } } }) : { foo: "bar", number: 1234, pi: 3.14159, date: (1464307200|date_modify('0sec')), empty: null, invalid-key: "hmm", multiline: "Multiple\\nLine\\nString\\n", object: { key: "value", datetime: (1605185652|date_modify('0sec')), values: { 0: "one", 1: "two" } } } %}

Configuring services in a Symfony project

Adjust your config/services.php as follows to register a FrontMatterLoader with a Converter\ToMultipleAssignmentsFrontMatterConverter:

<?php

declare(strict_types=1);

use Ergebnis\FrontMatter;
use Ergebnis\Twig;
use Symfony\Component\DependencyInjection;

return static function (DependencyInjection\Loader\Configurator\ContainerConfigurator $containerConfigurator): void {
    $services = $containerConfigurator->services();

    $services->defaults()
        ->autoconfigure()
        ->autowire();

    $services->alias(
        FrontMatter\Parser::class,
        FrontMatter\YamlParser::class,
    );

    $services->set(FrontMatter\YamlParser::class)
        ->class(FrontMatter\YamlParser::class);


    $services->set(Twig\FrontMatter\Converter\FrontMatterConverter::class)
        ->class(Twig\FrontMatter\Converter\ToMultipleAssignmentsFrontMatterConverter::class)
        ->args([
            '$force' => false, // or true, as you prefer
        ]);

    $services->set(Twig\FrontMatter\FrontMatterLoader::class)
        ->args([
            '$loader' => new DependencyInjection\Loader\Configurator\ReferenceConfigurator('twig.loader.native_filesystem'),
        ]);
});

Changelog

The maintainers of this project record notable changes to this project in a changelog.

Contributing

The maintainers of this project suggest following the contribution guide.

Code of Conduct

The maintainers of this project ask contributors to follow the code of conduct.

General Support Policy

The maintainers of this project provide limited support.

You can support the maintenance of this project by sponsoring @ergebnis.

PHP Version Support Policy

This project currently supports the following PHP versions:

• PHP 8.1 (has reached its end of life on December 31, 2025)
• PHP 8.2
• PHP 8.3
• PHP 8.4
• PHP 8.5

The maintainers of this project add support for a PHP version following its initial release and may drop support for a PHP version when it has reached its end of life.

Security Policy

This project has a security policy.

License

This project uses the MIT license.

Social

Follow @localheinz and @ergebnis on Twitter.