README

The most universal Front matter (yaml, json, neon, toml) parser and dumper for PHP. Front matter allows page-specific variables to be included at the top of a page.

Features

This library can parse all form of front matter:

---
foo: bar
---

# Section

Text

+++
foo = bar
+++

# Section

Text

{
  "foo": "bar"
}

# Section

Text

{#---
foo: bar
---#}

<h1>Section</h1>

<p>{{ foo }}</p>

--
  foo: bar

h1 Section

p= foo

Installation

This library can be installed via Composer:

composer require webuni/front-matter

Usage

Automatic front matter detection and parsing

The following code will automatically detect the above front matter types:

<?php

$frontMatter = \Webuni\FrontMatter\FrontMatterChain::create();
$document = $frontMatter->parse($string);

$data = $document->getData();
$content = $document->getContent();

Parse an arbitrary string

<?php

$frontMatter = new \Webuni\FrontMatter\FrontMatter();

$document = $frontMatter->parse($string);

$data = $document->getData();
$content = $document->getContent();

Check if a string has front matter

<?php

$frontMatter = new \Webuni\FrontMatter\FrontMatter();

$hasFrontMatter = $frontMatter->exists($string);

Twig loader

If you want to store metadata about twig template, e.g.:

{#---
title: Hello world
menu: main
weight: 20
---#}
{% extend layout.html.twig %}
{% block content %}
Hello world!
{% endblock %}

you can use FrontMatterLoader, that decorates another Twig loader:

$frontMatter = \Webuni\FrontMatter\Twig\TwigCommentFrontMatter::create();
$loader = new \Twig\Loader\FilesystemLoader(['path/to/templates']);
$loader = new \Webuni\FrontMatter\Twig\FrontMatterLoader($frontMatter, $loader);

$twig = new \Twig\Environment($loader);
$content = $twig->render('template', []);
// rendered the valid twig template without front matter

It is possible to inject front matter to Twig template as variables:

// …
$converter = \Webuni\FrontMatter\Twig\DataToTwigConvertor::vars();
$loader = new \Webuni\FrontMatter\Twig\FrontMatterLoader($frontMatter, $loader, $converter);
// …

Loaded Twig template has this code:

{% set title = "Hello world" %}
{% set menu = "main" %}
{% set weight = 20 %}
{% line 5 %}
{% extend layout.html.twig %}
{% block content %}
Hello world!
{% endblock %}

Available converters:

Markdown

The most commonly used front matter is for markdown files:

---
layout: post
title: I Love Markdown
tags:
  - test
  - example
---

# Hello World!

This library can be used with league/commonmark:

$frontMatter = new \Webuni\FrontMatter\FrontMatter();
$extension = new \Webuni\FrontMatter\Markdown\FrontMatterLeagueCommonMarkExtension($frontMatter);

$converter = new \League\CommonMark\CommonMarkConverter([]);
$converter->getEnvironment()->addExtension($extension);
$html = $converter->convertToHtml('markdown'); // html without front matter

Alternatives

• https://github.com/spatie/yaml-front-matter
• https://github.com/ergebnis/front-matter
• https://github.com/mnapoli/FrontYAML
• https://github.com/Modularr/YAML-FrontMatter