hkod / frontmatter
A context aware frontmatter parser that supports multiple formats and uses a clean OOP architecture
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
This package is auto-updated.
Last update: 2024-10-16 11:55:48 UTC
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();