YAML Front Matter

https://github.com/spatie/yaml-front-matter
Admin
A YAML front matter parser for PHP that extracts metadata from files with YAML content wrapped in...
Tokens:6,062
Snippets:42
Trust Score:10
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/spatie/yaml-front-matter/blob/main/README.md

Command to install the package using Composer.

```bash
$ composer require spatie/yaml-front-matter
```

--------------------------------

### Install YAML Front Matter via Composer

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

Use this command to add the library to your project dependencies.

```bash
composer require spatie/yaml-front-matter
```

--------------------------------

### Define YAML Front Matter

Source: https://github.com/spatie/yaml-front-matter/blob/main/README.md

Example of the expected file format with YAML metadata at the top.

```md
---
title: Example
---

Lorem ipsum.
```

--------------------------------

### YamlFrontMatter::markdownCompatibleParse()

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

A specialized parser for handling Markdown files that contain front matter examples within code blocks. It correctly identifies only the actual front matter at the document's beginning.

```APIDOC
## YamlFrontMatter::markdownCompatibleParse()

### Description
A specialized parser for handling Markdown files that contain front matter examples within code blocks. The standard parser may incorrectly interpret `---` delimiters inside code blocks as front matter boundaries. This method uses line-by-line analysis to correctly identify only the actual front matter at the document's beginning.

### Method
`markdownCompatibleParse(string $content): Document`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **content** (string) - Required - The string content to parse, potentially containing code blocks with front matter examples.

### Request Example
```php
<?php

use Spatie\YamlFrontMatter\YamlFrontMatter;

// Content with front matter AND code blocks containing front matter examples
$content = <<<MD
---
title: Front Matter Tutorial
category: documentation
---

# How to Use Front Matter

Here's an example of front matter syntax:

```yaml
---
title: Example Post
author: Jane Doe
---

Content goes here...
```

The code block above won't be parsed as actual front matter.
MD;

// Use markdownCompatibleParse for complex markdown with embedded examples
$document = YamlFrontMatter::markdownCompatibleParse($content);
```

### Response
#### Success Response (200)
- **Document** (object) - An object containing methods to access matter and body.
  - **matter()**: Returns an array of the parsed YAML front matter.
  - **matter(string $key)**: Returns a specific value from the front matter.
  - **body()**: Returns the content after the front matter, including code blocks.

#### Response Example
```php
// Only the actual front matter is extracted
$matter = $document->matter();
// Returns: ['title' => 'Front Matter Tutorial', 'category' => 'documentation']

// The body includes the code block intact
$body = $document->body();
// Contains the full markdown including the code block with front matter example
```
```

--------------------------------

### Parse Markdown Code Block

Source: https://github.com/spatie/yaml-front-matter/blob/main/tests/meta-document.md

This example shows how the parser handles a Markdown code block that itself contains YAML front matter. The outer front matter is parsed, while the inner code block remains as content.

```markdown
---
foo: bar
---

Lorem ipsum.

A paragraph in a Markdown Post.
This file contains a Markdown code block that the original parser does not handle.
See https://github.com/spatie/yaml-front-matter/discussions/30.

```
---
title: The Title of Markdown Code
---

A paragraph in Markdown Code
```
```

--------------------------------

### Parse Markdown with Embedded Front Matter Examples

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

Use this method when markdown content contains code blocks that include their own front matter delimiters, preventing incorrect parsing.

```php
<?php

use Spatie\YamlFrontMatter\YamlFrontMatter;

// Content with front matter AND code blocks containing front matter examples
$content = <<<MD
---
title: Front Matter Tutorial
category: documentation
---

# How to Use Front Matter

Here's an example of front matter syntax:

```yaml
---
title: Example Post
author: Jane Doe
---

Content goes here...
```

The code block above won't be parsed as actual front matter.
MD;

// Use markdownCompatibleParse for complex markdown with embedded examples
$document = YamlFrontMatter::markdownCompatibleParse($content);

// Only the actual front matter is extracted
$matter = $document->matter();
// Returns: ['title' => 'Front Matter Tutorial', 'category' => 'documentation']

// The body includes the code block intact
$body = $document->body();
// Contains the full markdown including the code block with front matter example
```

--------------------------------

### Run Tests

Source: https://github.com/spatie/yaml-front-matter/blob/main/README.md

Command to execute the test suite.

```bash
$ vendor/bin/phpunit
```

--------------------------------

### Parse File Contents

Source: https://github.com/spatie/yaml-front-matter/blob/main/README.md

Initial step to parse file contents into a YamlFrontMatterObject.

```php
use Spatie\YamlFrontMatter\YamlFrontMatter;
$object = YamlFrontMatter::parse(file_get_contents('example.md'));
```

--------------------------------

### Retrieve front matter with Document::matter()

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

Access front matter values using keys, dot notation for nested properties, or retrieve the entire array. Supports providing a default value for missing keys.

```php
<?php

use Spatie\YamlFrontMatter\YamlFrontMatter;

$content = <<<MD
---
title: Advanced Configuration
version: 2.0
meta:
  keywords:
    - php
    - yaml
    - parser
  author:
    name: Sebastian De Deyne
    email: sebastian@spatie.be
settings:
  debug: false
  cache_ttl: 3600
---

Document content here.
MD;

$document = YamlFrontMatter::parse($content);

// Get all front matter
$allMatter = $document->matter();
// Returns full nested array structure

// Get top-level value
$title = $document->matter('title');
// Returns: 'Advanced Configuration'

// Get nested value using dot notation
$authorName = $document->matter('meta.author.name');
// Returns: 'Sebastian De Deyne'

$keywords = $document->matter('meta.keywords');
// Returns: ['php', 'yaml', 'parser']

// Get deeply nested value
$cacheTtl = $document->matter('settings.cache_ttl');
// Returns: 3600

// Use default value for missing keys
$description = $document->matter('description', 'No description available');
// Returns: 'No description available'

$missingNested = $document->matter('meta.social.twitter', '@default');
// Returns: '@default'
```

--------------------------------

### Parse YAML Front Matter from a File

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

Reads and parses a file directly from the filesystem, providing a convenient wrapper for file operations.

```php
<?php

use Spatie\YamlFrontMatter\YamlFrontMatter;

// Parse a markdown file directly
$document = YamlFrontMatter::parseFile('/path/to/blog-post.md');

// Access front matter
$title = $document->matter('title');
$author = $document->matter('author');

// Get the body content
$content = $document->body();

// Example: Processing multiple markdown files
$files = glob('/path/to/posts/*.md');
foreach ($files as $file) {
    $document = YamlFrontMatter::parseFile($file);
    echo "Title: " . $document->matter('title') . "\n";
    echo "Body length: " . strlen($document->body()) . " characters\n";
}
```

--------------------------------

### Access front matter via magic properties

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

Access top-level front matter keys directly as object properties. Undefined properties return null.

```php
<?php

use Spatie\YamlFrontMatter\YamlFrontMatter;

$content = <<<MD
---
title: My Article
author: John Smith
date: 2024-01-15
published: true
tags:
  - news
  - featured
---

Article content goes here.
MD;

$document = YamlFrontMatter::parse($content);

// Access front matter as properties
$title = $document->title;       // Returns: 'My Article'
$author = $document->author;     // Returns: 'John Smith'
$date = $document->date;         // Returns: '2024-01-15'
$published = $document->published; // Returns: true
$tags = $document->tags;         // Returns: ['news', 'featured']

// Undefined properties return null
$category = $document->category; // Returns: null

// Example: Building a blog post object
$post = (object) [
    'title' => $document->title,
    'author' => $document->author,
    'date' => new DateTime($document->date),
    'content' => $document->body(),
    'isPublished' => $document->published ?? false,
];
```

--------------------------------

### Magic Property Access - Accessing Front Matter as Properties

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

The `Document` class implements the `__get()` magic method, allowing front matter values to be accessed directly as object properties for a more convenient syntax.

```APIDOC
## Magic Property Access

### Description
The Document class implements `__get()` magic method, allowing front matter values to be accessed as object properties. This provides a more convenient syntax for accessing top-level front matter keys.

### Method
Access front matter values directly as properties of the `Document` object.

### Parameters
No explicit parameters. Access properties by their front matter key name.

### Request Example
```php
<?php

use Spatie\YamlFrontMatter\YamlFrontMatter;

$content = "---\ntitle: My Article\nauthor: John Smith\ndate: 2024-01-15\npublished: true\ntags:\n  - news\n  - featured\n---

Article content goes here.
MD;

$document = YamlFrontMatter::parse($content);

// Access front matter as properties
$title = $document->title;       // Returns: 'My Article'
$author = $document->author;     // Returns: 'John Smith'
$date = $document->date;         // Returns: '2024-01-15'
$published = $document->published; // Returns: true
$tags = $document->tags;         // Returns: ['news', 'featured']

// Undefined properties return null
$category = $document->category; // Returns: null

// Example: Building a blog post object
$post = (object) [
    'title' => $document->title,
    'author' => $document->author,
    'date' => new DateTime($document->date),
    'content' => $document->body(),
    'isPublished' => $document->published ?? false,
];
```

### Response
#### Success Response (200)
- **mixed** - Returns the value of the corresponding front matter key if it exists. Returns `null` if the property (front matter key) does not exist.
```

--------------------------------

### Retrieve document body with Document::body()

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

Extracts the content following the YAML front matter delimiter. Leading whitespace is automatically trimmed.

```php
<?php

use Spatie\YamlFrontMatter\YamlFrontMatter;

$content = <<<MD
---
title: Getting Started
---

## Introduction

Welcome to the documentation. This guide will help you get started.

### Prerequisites

- PHP 8.0 or higher
- Composer installed

### Installation Steps

1. Run composer require
2. Configure your settings
3. Start using the library
MD;

$document = YamlFrontMatter::parse($content);

// Get the full body content
$body = $document->body();

// The body contains all content after the front matter
echo $body;
// Output:
// ## Introduction
//
// Welcome to the documentation. This guide will help you get started.
//
// ### Prerequisites
// ...

// Common use case: Render markdown body with a markdown parser
// $html = (new Parsedown())->text($document->body());
```

--------------------------------

### Parse and Access Front Matter

Source: https://github.com/spatie/yaml-front-matter/blob/main/README.md

Basic usage for parsing a file and accessing its metadata and body content.

```php
use Spatie\YamlFrontMatter\YamlFrontMatter;

$object = YamlFrontMatter::parse(file_get_contents(__DIR__.'/example.md'));

$object->matter('title'); // => 'Example';
$object->body(); // => 'Lorem ipsum.'

// Or retrieve front matter with a property call...

$object->title; // => 'Example';
```

--------------------------------

### YamlFrontMatter::parseFile()

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

Reads and parses a file directly from the filesystem. This is a convenience method that wraps file_get_contents() and parse() into a single call.

```APIDOC
## YamlFrontMatter::parseFile()

### Description
Reads and parses a file directly from the filesystem without needing to manually read its contents. This is a convenience method that wraps file_get_contents() and parse() into a single call.

### Method
`parseFile(string $filePath): Document`

### Parameters
#### Path Parameters
- **filePath** (string) - Required - The path to the file to parse.

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
<?php

use Spatie\YamlFrontMatter\YamlFrontMatter;

// Parse a markdown file directly
$document = YamlFrontMatter::parseFile('/path/to/blog-post.md');

// Access front matter
$title = $document->matter('title');
$author = $document->matter('author');

// Get the body content
$content = $document->body();

// Example: Processing multiple markdown files
$files = glob('/path/to/posts/*.md');
foreach ($files as $file) {
    $document = YamlFrontMatter::parseFile($file);
    echo "Title: " . $document->matter('title') . "\n";
    echo "Body length: " . strlen($document->body()) . " characters\n";
}
```

### Response
#### Success Response (200)
- **Document** (object) - An object containing methods to access matter and body.
  - **matter()**: Returns an array of the parsed YAML front matter.
  - **matter(string $key)**: Returns a specific value from the front matter.
  - **body()**: Returns the content after the front matter.

#### Response Example
```php
// Access front matter
$title = $document->matter('title');
$author = $document->matter('author');

// Get the body content
$content = $document->body();
```
```

--------------------------------

### Parse YAML Front Matter from a String

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

Extracts metadata and body content from a string using the parse method. Returns a Document object containing the parsed data.

```php
<?php

use Spatie\YamlFrontMatter\YamlFrontMatter;

$content = <<<MD
---
title: My Blog Post
author: John Doe
tags:
  - php
  - tutorial
published: true
---

# Welcome to My Blog

This is the main content of the post.
MD;

$document = YamlFrontMatter::parse($content);

// Get all front matter as an array
$matter = $document->matter();
// Returns: ['title' => 'My Blog Post', 'author' => 'John Doe', 'tags' => ['php', 'tutorial'], 'published' => true]

// Get a specific front matter value
$title = $document->matter('title');
// Returns: 'My Blog Post'

// Get the body content (everything after the closing ---)
$body = $document->body();
// Returns: "# Welcome to My Blog\n\nThis is the main content of the post."
```

--------------------------------

### Parse YAML Front Matter from Markdown

Source: https://github.com/spatie/yaml-front-matter/blob/main/tests/meta-document.md

Use this method to parse YAML front matter from a Markdown string. It returns an array containing the front matter and the content.

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Spatie\YamlFrontMatter\YamlFrontMatter;

$markdown = "---\ntitle: My Awesome Title\nauthor: John Doe\n---\n\nThis is the content of my markdown file.";

$parsed = YamlFrontMatter::parse($markdown);

echo $parsed->matter('title'); // Output: My Awesome Title
echo $parsed->body();      // Output: This is the content of my markdown file.
```

--------------------------------

### Parse Front Matter with No Body

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

If front matter exists but there is no content body, the parser extracts the matter and returns an empty string for the body.

```php
// Front matter with no body
$noBody = "---\ntitle: Metadata Only
---";
$doc2 = YamlFrontMatter::parse($noBody);
$doc2->matter();  // Returns: ['title' => 'Metadata Only']
$doc2->body();    // Returns: ""
```

--------------------------------

### Document::matter() - Accessing Front Matter

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

Retrieves front matter values from the parsed document. It can return all front matter as an array, a specific value by key, or use dot notation for nested properties with optional default values.

```APIDOC
## Document::matter()

### Description
Retrieves front matter values from the parsed document. When called without arguments, returns all front matter as an associative array. When called with a key, returns that specific value. Supports dot notation for accessing nested properties and accepts a default value for missing keys.

### Method
`matter(string $key = null, $defaultValue = null)`

### Parameters
#### Query Parameters
- **key** (string) - Optional - The key of the front matter to retrieve. Supports dot notation for nested properties.
- **defaultValue** - Optional - The default value to return if the key is not found.

### Request Example
```php
<?php

use Spatie\YamlFrontMatter\YamlFrontMatter;

$content = "---\ntitle: Advanced Configuration\nversion: 2.0\nmeta:\n  keywords:\n    - php\n    - yaml\n    - parser\n  author:\n    name: Sebastian De Deyne\n    email: sebastian@spatie.be\nsettings:\n  debug: false\n  cache_ttl: 3600\n---

Document content here.
MD;

$document = YamlFrontMatter::parse($content);

// Get all front matter
$allMatter = $document->matter();
// Returns full nested array structure

// Get top-level value
$title = $document->matter('title');
// Returns: 'Advanced Configuration'

// Get nested value using dot notation
$authorName = $document->matter('meta.author.name');
// Returns: 'Sebastian De Deyne'

$keywords = $document->matter('meta.keywords');
// Returns: ['php', 'yaml', 'parser']

// Get deeply nested value
$cacheTtl = $document->matter('settings.cache_ttl');
// Returns: 3600

// Use default value for missing keys
$description = $document->matter('description', 'No description available');
// Returns: 'No description available'

$missingNested = $document->matter('meta.social.twitter', '@default');
// Returns: '@default'
```

### Response
#### Success Response (200)
- **array** - Returns all front matter as an associative array if no key is provided.
- **mixed** - Returns the value associated with the specified key, or the default value if the key is not found.
```

--------------------------------

### Handle Markdown with No Front Matter

Source: https://github.com/spatie/yaml-front-matter/blob/main/tests/meta-document.md

When a Markdown file does not contain YAML front matter, the parser will return an empty array for the matter and the full content as the body.

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Spatie\YamlFrontMatter\YamlFrontMatter;

$markdown = "This is a markdown file without any front matter.";

$parsed = YamlFrontMatter::parse($markdown);

print_r($parsed->matter()); // Output: Array()
echo $parsed->body();      // Output: This is a markdown file without any front matter.
```

--------------------------------

### Parse Content with No Front Matter

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

When content lacks front matter, the parser returns empty matter and the full content as the body.

```php
<?php

use Spatie\YamlFrontMatter\YamlFrontMatter;

// Content with no front matter - returns empty matter, full content as body
$noFrontMatter = "Just regular content without any front matter.";
$doc1 = YamlFrontMatter::parse($noFrontMatter);
$doc1->matter();  // Returns: []
$doc1->body();    // Returns: "Just regular content without any front matter."
```

--------------------------------

### YamlFrontMatter::parse()

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

Parses a string containing YAML front matter and returns a Document object. Extracts matter and body content separately. Handles cases with no valid front matter.

```APIDOC
## YamlFrontMatter::parse()

### Description
Parses a string containing YAML front matter and returns a Document object with the extracted matter and body content. The front matter must be enclosed between two `---` delimiters at the beginning of the content. If no valid front matter is found, returns an empty matter array with the full content as the body.

### Method
`parse(string $content): Document`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **content** (string) - Required - The string content to parse.

### Request Example
```php
<?php

use Spatie\YamlFrontMatter\YamlFrontMatter;

$content = <<<MD
---
title: My Blog Post
author: John Doe
tags:
  - php
  - tutorial
published: true
---

# Welcome to My Blog

This is the main content of the post.
MD;

$document = YamlFrontMatter::parse($content);
```

### Response
#### Success Response (200)
- **Document** (object) - An object containing methods to access matter and body.
  - **matter()**: Returns an array of the parsed YAML front matter.
  - **matter(string $key)**: Returns a specific value from the front matter.
  - **body()**: Returns the content after the front matter.

#### Response Example
```php
// Get all front matter as an array
$matter = $document->matter();
// Returns: ['title' => 'My Blog Post', 'author' => 'John Doe', 'tags' => ['php', 'tutorial'], 'published' => true]

// Get a specific front matter value
$title = $document->matter('title');
// Returns: 'My Blog Post'

// Get the body content (everything after the closing ---)
$body = $document->body();
// Returns: "# Welcome to My Blog\n\nThis is the main content of the post."
```
```

--------------------------------

### Query Parsed Object

Source: https://github.com/spatie/yaml-front-matter/blob/main/README.md

Methods to retrieve metadata and body content from the parsed object.

```php
$object->matter(); // => ['title' => 'Example']
$object->matter('title'); // => 'Example'
$object->body(); // => 'Lorem ipsum.'
$object->title; // => 'Example'
```

--------------------------------

### Document::body() - Accessing Document Body

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

Returns the body content of the document as a string. The body is defined as everything that appears after the closing `---` delimiter, with leading whitespace trimmed.

```APIDOC
## Document::body()

### Description
Returns the body content of the document as a string. The body is everything that appears after the closing `---` delimiter, with leading whitespace trimmed appropriately.

### Method
`body(): string`

### Parameters
This method does not accept any parameters.

### Request Example
```php
<?php

use Spatie\YamlFrontMatter\YamlFrontMatter;

$content = "---\ntitle: Getting Started\n---

## Introduction

Welcome to the documentation. This guide will help you get started.

### Prerequisites

- PHP 8.0 or higher
- Composer installed

### Installation Steps

1. Run composer require
2. Configure your settings
3. Start using the library
MD;

$document = YamlFrontMatter::parse($content);

// Get the full body content
$body = $document->body();

// The body contains all content after the front matter
echo $body;
// Output:
// ## Introduction
// 
// Welcome to the documentation. This guide will help you get started.
// 
// ### Prerequisites
// ...

// Common use case: Render markdown body with a markdown parser
// $html = (new Parsedown())->text($document->body());
```

### Response
#### Success Response (200)
- **string** - The body content of the document.
```

--------------------------------

### Parse Invalid or Incomplete Front Matter

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

Content with incomplete or invalid front matter (e.g., only one delimiter) is treated as regular content, returning empty matter and the original content as the body.

```php
// Invalid/incomplete front matter (only one delimiter)
$invalid = "---\nfoo: bar\n\nThis is not valid front matter.";
$doc4 = YamlFrontMatter::parse($invalid);
$doc4->matter();  // Returns: []
$doc4->body();    // Returns the original content
```

--------------------------------

### Parse Front Matter Without Trailing Newline

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

The parser correctly handles front matter even if there is no newline character immediately following the closing delimiter.

```php
// Front matter with no newline after closing delimiter
$noNewline = "---\ntitle: Compact
---";
$doc3 = YamlFrontMatter::parse($noNewline);
$doc3->matter('title');  // Returns: 'Compact'
```

--------------------------------

### Parse Front Matter Value Containing Delimiter Characters

Source: https://context7.com/spatie/yaml-front-matter/llms.txt

The parser correctly extracts front matter values even if they contain characters that resemble the delimiters.

```php
// Front matter value containing delimiter characters
$withDelimiter = "---\ntitle: Section---Subsection
---\nContent";
$doc5 = YamlFrontMatter::parse($withDelimiter);
$doc5->matter('title');  // Returns: 'Section---Subsection'
```
Tokens:
Raw