ergebnis/front-matter

Provides a front matter parser.

3.3.0 2025-05-03 09:42 UTC

Requires

• php: ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0
• symfony/yaml: ^5.0.0 || ^6.0.0 || ^7.0.0

Requires (Dev)

• ergebnis/composer-normalize: ^2.47.0
• ergebnis/data-provider: ^3.4.0
• ergebnis/license: ^2.6.0
• ergebnis/php-cs-fixer-config: ~6.46.0
• ergebnis/phpunit-slow-test-detector: ^2.19.1
• fakerphp/faker: ^1.24.1
• infection/infection: ~0.27.11
• phpstan/extension-installer: ^1.4.3
• phpstan/phpstan: ^2.1.14
• phpstan/phpstan-deprecation-rules: ^2.0.2
• phpstan/phpstan-phpunit: ^2.0.6
• phpstan/phpstan-strict-rules: ^2.0.4
• phpunit/phpunit: ^10.5.27
• rector/rector: ^2.0.12
• roave/backward-compatibility-check: ^8.6.0

MIT

• Andreas Möller

README

This project provides a composer package with a front matter parser.

Installation

Run

composer require ergebnis/front-matter

Usage

This packages comes with an Ergebnis\FrontMatter\Parser interface and provides the following parsers:

• Ergebnis\FrontMatter\YamlParser

YamlParser

With the YamlParser, you can test if a string has YAML front matter:

<?php

declare(strict_types=1);

use Ergebnis\FrontMatter;

$parser = new FrontMatter\YamlParser();

$unparsedContentWithoutFrontMatter = FrontMatter\Content::fromString('Hello, how are you today?');

$parser->hasFrontMatter($unparsedContentWithoutFrontMatter); // false

$unparsedContentWithFrontMatter = FrontMatter\Content::fromString(<<<TXT
---
page:
  title: "Hello"
  description: "Good to see you, how can I help you?"
---
TXT);

$parser->hasFrontMatter($unparsedContentWithFrontMatter); // true

With the YamlParser, you can parse a string, regardless of whether it has YAML front matter or not.

<?php

declare(strict_types=1);

use Ergebnis\FrontMatter;

$parser = new FrontMatter\YamlParser();

$unparsedContentWithoutFrontMatter = FrontMatter\Content::fromString('Hello, how are you today?');

/** @var FrontMatter\Parsed $parsedWithoutFrontMatter */
$parsedWithoutFrontMatter = $parser->parse($unparsedContentWithoutFrontMatter);

$unparsedContentWithFrontMatter = FrontMatter\Content::fromString(<<<TXT
---
page:
  title: "Hello"
  description: "Good to see you, how can I help you?"
---
TXT);

/** @var FrontMatter\Parsed $parsedWithFrontMatter */
$parsedWithFrontMatter = $parser->parse($unparsedContentWithoutFrontMatter);

var_dump($parsedWithFrontMatter->frontMatter()->data()->has('page.title')); // true
var_dump($parsedWithFrontMatter->frontMatter()->data()->get('page.title')); // "Hello"

❗ The YamlParser will throw an Ergebnis\FrontMatter\Exception\FrontMatterCanNotBeParsed exception when the front matter is invalid YAML and an Ergebnis\FrontMatter\Exception\FrontMatterIsNotAnObject exception when the front matter does not describe an object.

💡 The YamlParser returns an Ergebnis\FrontMatter\Parsed value object on success, regardless of whether the value has front matter or not.

Changelog

The maintainers of this project record notable changes to this project in a changelog.

Contributing

The maintainers of this project suggest following the contribution guide.

Code of Conduct

The maintainers of this project ask contributors to follow the code of conduct.

General Support Policy

The maintainers of this project provide limited support.

You can support the maintenance of this project by sponsoring @ergebnis.

PHP Version Support Policy

This project supports PHP versions with active and security support.

The maintainers of this project add support for a PHP version following its initial release and drop support for a PHP version when it has reached the end of security support.

Security Policy

This project has a security policy.

License

This project uses the MIT license.

Credits

This project is inspired by webuni/front-matter, originally licensed under MIT by Martin Hasoň.

Social

Follow @localheinz and @ergebnis on Twitter.