Frontmatter parser

[WIP] Frontmatter Jekyll style parser

Available parsers:

• yaml (use symfony/yaml)
• Markdown (use erusev/parsedown-extra)
• Json (use seld/jsonlint)

Install

Via Composer

$ composer require devster/frontmatter

And add extra packages that built-in parsers use:

# YAML
$ composer require symfony/yaml
# Markdown
$ composer require erusev/parsedown-extra
# Json
$ composer require seld/jsonlint

These packages are not required by default to minimize the footprint and speed up your install if you only need few of them

Usage

Basic usage

require'../vendor/autoload.php';
$parser = newDevster\Frontmatter\Parser('yaml', 'markdown');
$content = <<<EOF---title: My Contentdescription: "This is a description"---This is *Markdown* contentEOF;
$frontmatter = $parser->parse($content);
echo$frontmatter->head['title']; // My contentecho$frontmatter->getBody(); // This is <em>Markdown</em> content

And because the frontmatter format is not only used by developers, this parser is quite permissive

All content examples above are parsed like normal frontmatter content:

$content = <<<EOF --- title: My Title ---# Title 1## Title 2EOF;
$content = <<<EOF --- title: My Title ---# Title 1## Title 2EOF;

Just parse frontmatter, and don't process head and body

$p = newParser;
$result = $p->parseFrontmatter($content);
echo$result['head'];
echo$result['body'];

Customize the frontmatter delimiter

$p = newParser('json', 'markdown', '##');
$p->parse(<<<EOF##{ "title": "My title" }##Body contentEOF);
// You can also let your user use its own delimiter$p = newParser;
$p
->guessDelimiter()
->parse(<<<EOF~~X~~head~~X~~bodyEOF);

Guess parsers from filename

The frontmatter parsers can be guessed from a filename, based on the extensions.

Take a look at these examples below:

• my_file.json.md: Head in Json and Body in Markdown
• my_file.md: Head will be parse with the parser set in the constructor, Body in Markdown
• my_file.unknown: An exception will be thrown
• my_file.yml.unknown: An exception will be thrown

$p = newParser;
$p
->guessParsersFromFilename('my_file.yml.md')
->parse(file_gets_content('my_file.yml.md'))
;
// Or you can set the default head parser$p = newParser('json');
$p
->guessParsersFromFilename('my_file.md')
->parse(file_gets_content('my_file.md'))
;

Guess body parser from head

You can also define explicitly in the head which parser the body should be parsed with.

$p = newParser('yaml');
$p
->guessBodyParserFromHead('[options][format]')
->parse(<<<EOF---title: My Titleoptions: format: json---{ "body": "This is my body"}EOF);

Internally the Property Access Component from symfony is used. Refer to its documentation to find the path that will be used to grab the parser from the head

If the parser could not be fetch from the head, the default body parser will be use.

More complex usage

$p = newDevster\Frontmatter\Parser('yml', 'md');
$p
->guessDelimiter()
->guessParsersFromFilename('my_file.md')
->guessBodyParserFromHead('[format]')
;
try {
$p->parse($content);
} catch (Devster\Frontmatter\Exception\Exception$e) {
if ($einstanceofDevster\Frontmatter\Exception\ParserNotFoundException) {
// The head or the body parser is not found
}
if ($einstanceofDevster\Frontmatter\Exception\ParsingException) {
// Unable to parse the frontmatter content// or// an error occured in head or body parsing
}
}

Testing

$ vendor/bin/phpunit

Roadmap

• Rename head to header
• Add an INI parser
• Allow to not parse the body to avoid the creation of a new custom parser if the need is not built-in
• Add a validate feature
• Add dumping feature

Contributing

Please see CONTRIBUTING for details.

Credits

Special thank to Etienne Zannelli for his help on Regex ❤

• All Contributors

License

The MIT License (MIT). Please see License File for more information.