webuni / front-matter
Front matter parser and dumper for PHP
Installs: 235 781
Dependents: 13
Suggesters: 0
Security: 0
Stars: 35
Watchers: 3
Forks: 9
Open Issues: 0
Requires
- php: ^7.4 || ^8.0
- symfony/yaml: ^3.4.31 || ^4.3.4 || ^5.0 || ^6.0 || ^7.0
Requires (Dev)
- ext-json: *
- friendsofphp/php-cs-fixer: ^3.41
- league/commonmark: ^2.0
- mthaml/mthaml: ^1.3
- nette/neon: ^2.2 || ^3.0
- phpstan/phpstan: ^1.10
- phpunit/phpunit: ^9.6
- twig/twig: ^3.0
- yosymfony/toml: ^1.0
Suggests
- nette/neon: If you want to use NEON as front matter
- yosymfony/toml: If you want to use TOML as front matter
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.
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:
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