ALTO Front Matter

Fast front matter extraction and strict YAML-subset decoding for PHP.

         

ALTO Front Matter reads the fenced metadata block at the top of a document and returns a typed, read-only accessor. It has no runtime Composer dependencies, does not retain the document body, and rejects unsupported YAML instead of silently reinterpreting it.

use Alto\FrontMatter\FrontMatter;

$metadata = FrontMatter::fromString($document);

$title = $metadata->getString('title');
$draft = $metadata->getBoolean('draft', false);
$tags = $metadata->all('tags');

The decoder follows the YAML 1.2 core schema over a deliberately strict subset. Its parser is single-pass, reports the first syntax error with a line and column, and is covered by a 100% line-coverage quality gate.

Installation

Install ALTO Front Matter with Composer:

composer require alto/frontmatter

ALTO Front Matter requires PHP 8.4 or later and has no runtime PHP extension or Composer package requirements.

Quick Start

use Alto\FrontMatter\FrontMatter;

$document = <<<'MARKDOWN'
---
title: Hello World
draft: false
tags: [php, alto]
---
# Hello World
MARKDOWN;

$metadata = FrontMatter::fromString($document);

echo $metadata->getString('title');
$body = substr($document, $metadata->sourceOffset() + $metadata->sourceLength());

fromString() returns empty metadata when the document has no front matter and throws when a detected block is malformed. Use fromFile() when the package should read the file for you.

Documentation

Guide	Contents
Documentation index	Browse the complete guide set
Getting started	Read metadata and locate the body
Typed metadata	Accessors, defaults, enums, and dates
Decoding	The supported YAML subset and raw blocks
Rendering	Generate YAML, JSON, and TOML front matter
Integration	Decoder and renderer contracts
Errors	Exception hierarchy and recovery
Design	Guarantees, tradeoffs, and limitations

Contributing

Contributions of all kinds are welcome. Visit the project on GitHub to report a bug, suggest a feature, or open a pull request.

Before submitting code, run:

# Runs PHP CS Fixer, PHPStan, and PHPUnit
composer qa

Run composer coverage separately to enforce the 100% line-coverage floor.

Support

ALTO Front Matter is open source. You can support its continued development through GitHub Sponsors.

Sharing this package with others or starring it on GitHub is also much appreciated.

License

ALTO Front Matter is released by ALTO PHP under the MIT License.