hkod/frontmatter

A context aware frontmatter parser that supports multiple formats and uses a clean OOP architecture

1.1.0 2018-02-11 13:24 UTC

Requires

• php: >=7.0

Requires (Dev)

• erusev/parsedown: ^1
• mustache/mustache: ^2
• symfony/yaml: >=3, <5

Suggests

• erusev/parsedown: For parsing Markdown
• mustache/mustache: For parsing Mustache templates
• symfony/yaml: For parsing YAML

Unlicense

• Hannes Forsgård

• metadata
• frontmatter

README

A context aware frontmatter parser that supports multiple formats and uses a clean OOP architecture.

Front matter is metadata located at the top of a file wrapped in delimiting line tokens, usually ---. The front matter may be formatted using YAML, Json or any ohter simliar format such as NEON or TOML.

Supported formats:

• Json
• INI
• YAML (require symfony/yaml)
• Markdown (require erusev/parsedown)
• Mustache (require mustache/mustache)

Parsers are simple callables, super easy to add more formats.

Installation

composer require hkod/frontmatter

Usage

A standard parser with yaml frontmatter and markdown body:

$parser = new \hkod\frontmatter\Parser(
    new \hkod\frontmatter\YamlParser,
    new \hkod\frontmatter\MarkdownParser
);

$result = $parser->parse("---
key: value
---
This is a **template**
");

// value
echo $result->getFrontmatter()['key'];

// <p>This is a <strong>template</strong></p>
echo $result->getBody();

Specify the front matter delimiter

Note that the delimiting tokens always represents full lines.

You may set the delimiters when creating the block parser.

$parser = new \hkod\frontmatter\Parser(
    new \hkod\frontmatter\VoidParser,
    new \hkod\frontmatter\VoidParser,
    new \hkod\frontmatter\BlockParser('***', '***')
);

$result = $parser->parse("***
frontmatter
***
body
");

// frontmatter
echo $result->getFrontmatter();

Putting the frontmatter last

Note that since the delimiting tokens represent a line the last line must end whit a new line (or similar) or it won't be recognized by the parser.

Frontmatter also supports an inverted block parser, where the frontmatter is expected to bee last instead of first.

$parser = new \hkod\frontmatter\Parser(
    new \hkod\frontmatter\VoidParser,
    new \hkod\frontmatter\VoidParser,
    new \hkod\frontmatter\InvertedBlockParser
);

$result = $parser->parse("
This is a the body
---
This is the frontmatter
---
");

// "This is the frontmatter"
echo $result->getFrontmatter();

Passing a context

When parsing you may pass a context to the parser and it will in turn be passed along to all subsequent parsers. Context dependet parsers may for example expand templates...

$parser = new \hkod\frontmatter\Parser(
    new \hkod\frontmatter\VoidParser,
    new \hkod\frontmatter\MustacheParser
);

$context = ['variable' => 'foobar'];

$result = $parser->parse("{{variable}}", $context);

// foobar
echo $result->getBody();

Creating complex parsers

$parser = (new \hkod\frontmatter\ParserBuilder)
    ->addFrontmatterPass(new \hkod\frontmatter\MustacheParser)
    ->addFrontmatterPass(new \hkod\frontmatter\YamlParser)
    ->addBodyPass(new \hkod\frontmatter\MustacheParser)
    ->addBodyPass(new \hkod\frontmatter\MarkdownParser)
    ->setBlockParser(new \hkod\frontmatter\BlockParser('***', '***'))
    ->buildParser();

$document = "***
key: {{variable}}
***
This is a **{{text}}** template
";

$context = ['variable' => 'value', 'text' => 'markdown'];

$result = $parser->parse($document, $context);

// value
echo $result->getFrontmatter()['key'];

// <p>This is a <strong>markdown</strong> template</p>
echo $result->getBody();