https://github.com/webuni/front-matter
The most featured front matter (yaml, json, neon, toml) parser and dumper for PHP.
https://github.com/webuni/front-matter
commonmark front-matter json markdown neon php toml twig yaml
Last synced: 26 days ago
JSON representation
The most featured front matter (yaml, json, neon, toml) parser and dumper for PHP.
- Host: GitHub
- URL: https://github.com/webuni/front-matter
- Owner: webuni
- License: mit
- Created: 2015-06-23T14:19:27.000Z (almost 10 years ago)
- Default Branch: main
- Last Pushed: 2025-01-04T22:24:52.000Z (4 months ago)
- Last Synced: 2025-03-29T02:06:24.728Z (about 1 month ago)
- Topics: commonmark, front-matter, json, markdown, neon, php, toml, twig, yaml
- Language: PHP
- Homepage:
- Size: 114 KB
- Stars: 35
- Watchers: 2
- Forks: 10
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Front Matter
============
[](https://packagist.org/packages/webuni/front-matter)
[](https://sonarcloud.io/summary/new_code?id=webuni_front-matter)
[](https://sonarcloud.io/summary/new_code?id=webuni_front-matter)
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.
Installation
------------
This library can be installed via Composer:
composer require webuni/front-matter
Usage
-----
### Automatic front matter detection and parsing
This library can parse all form of front matter:
YAML (Neon)TOMLTwigPugJson
```markdown
---
foo: bar
---
# Section
Text
```
```markdown
+++
foo = bar
+++
# Section
Text
```
```markdown
{#---
foo: bar
---#}
Section
{{ foo }}
```
```markdown
--
foo: bar
h1 Section
p= foo
```
```markdown
{
"foo": "bar"
}
# Section
Text
```
The following code will automatically detect the above front matter types:
```php
parse($string);
$data = $document->getData();
$content = $document->getContent();
```
### Parse an arbitrary string
```php
parse($string);
$data = $document->getData();
$content = $document->getContent();
```
### Check if a string has front matter
```php
exists($string);
```
### Twig loader
If you want to store metadata about twig template, e.g.:
```twig
{#---
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:
```php
$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:
```php
// …
$converter = \Webuni\FrontMatter\Twig\DataToTwigConvertor::vars();
$loader = new \Webuni\FrontMatter\Twig\FrontMatterLoader($frontMatter, $loader, $converter);
// …
```
Loaded Twig template has this code:
```twig
{% set title = "Hello world" %}
{% set menu = "main" %}
{% set weight = 20 %}
{% line 5 %}
{% extend layout.html.twig %}
{% block content %}
Hello world!
{% endblock %}
```
Available converters:
| Converter | Twig |
| ----------------------------------------- |------------------------------------------------------------|
| `DataToTwigConvertor::nothing()` | |
| `DataToTwigConvertor::vars()` | `{% set key1 = value1 %}` |
| `DataToTwigConvertor::vars(false)` | `{% set key1 = key1 is defined ? key1 : value1 %}` |
| `DataToTwigConvertor::var('name')` | `{% set name = {key1: value1, key2: value2} %}` |
| `DataToTwigConvertor::var('name', false)` | `{% set name = name is defined ? name : {key1: value1} %}` |
### Markdown
The most commonly used front matter is for markdown files:
```markdown
---
layout: post
title: I Love Markdown
tags:
- test
- example
---
# Hello World!
```
This library can be used with [league/commonmark](https://commonmark.thephpleague.com/):
```php
$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