DOCSEARCHbyAlgolia
Submit Docs

spatie/yaml-front-matter

repository·main·Indexed 43 days ago

https://github.com/spatie/yaml-front-matter

A lightweight PHP package for parsing YAML front matter from files and strings. It separates metadata wrapped in triple dashes from the main document body, providing the YamlFrontMatter::parse(), YamlFrontMatter::parseFile(), and YamlFrontMatter::markdownCompatibleParse() methods to extract data into a Document object.

Tokens
1.4K
Snippets
9
Records
9
Agent score
56%

What's inside spatie/yaml-front-matter

  3. Use the YamlFrontMatterObject to access data

    main

    The YamlFrontMatter::parse() method returns a YamlFrontMatterObject. You can interact with this object to retrieve the parsed metadata or the file body using several methods and property accessors:

    • $object->matter(): Returns all parsed front matter as an associative array.
    • $object->matter('key'): Returns the value for a specific key. Supports dot notation for nested fields (e.g., $object->matter('meta.keywords')).
    • $object->body(): Returns the content of the file excluding the front matter.
    • Dynamic Properties: You can access front matter keys directly as properties on the object (e.g., $object->title).
    use Spatie\YamlFrontMatter\YamlFrontMatter;

$object = YamlFrontMatter::parse("---\ntitle: Example\n---\n\nLorem ipsum.");

$object->matter();          // => ['title' => 'Example']
$object->matter('title');   // => 'Example'
$object->matter('meta.id'); // => Supports dot notation for nested YAML
$object->body();           // => 'Lorem ipsum.'
$object->title;             // => 'Example';

  4. Parse YAML front matter from a file with YamlFrontMatter::parseFile()

    main

    Use YamlFrontMatter::parseFile() to read a file from a given path and parse its YAML front matter. This is a convenience method that wraps file_get_contents() and parse().

    use Spatie\YamlFrontMatter\YamlFrontMatter;

$document = YamlFrontMatter::parseFile(__DIR__ . '/example.md');

  5. Parse Markdown containing Markdown with YamlFrontMatter::markdownCompatibleParse()

    main

    Standard parsing might fail or behave unexpectedly if the body of your document contains its own --- delimiters (e.g., code blocks or nested Markdown). Use YamlFrontMatter::markdownCompatibleParse() to use the ComplexMarkdownParser, which is designed to handle Markdown files that contain nested Markdown structures correctly.

    use Spatie\YamlFrontMatter\YamlFrontMatter;

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

  6. Parse YAML front matter from a string with YamlFrontMatter::parse()

    main

    Use YamlFrontMatter::parse() to extract YAML front matter and the remaining content from a string. The method looks for content delimited by --- separators. If no valid front matter is found, it returns a Document object containing an empty array for the matter and the original string as the body.

    use Spatie\YamlFrontMatter\YamlFrontMatter;

$document = YamlFrontMatter::parse("---\nfoo: bar\n---\n\nHello world!");

$matter = $document->matter(); // ['foo' => 'bar']
$body = $document->body();      // "\nHello world!"

  7. Access front matter and body using the Document class

    main

    The Document class represents a parsed file containing YAML front matter and a body. You can retrieve the entire front matter array, specific keys using dot notation, or the raw file body.

    • To get the entire front matter: Call matter() with no arguments.
    • To get a specific key: Call matter('key_name') or access it as a dynamic property $document->key_name.
    • To get the file body: Call body().

    When using matter($key, $default), if the key is not found, it returns the provided $default value.

    // Assuming $document is an instance of Spatie\YamlFrontMatter\Document

// Get all front matter
$allMatter = $document->matter();

// Get a specific key with a default value
$title = $document->matter('title', 'Untitled');

// Access via dynamic property
$author = $document->author;

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

  8. Retrieve specific front matter values with matter()

    main

    The matter() method allows you to retrieve specific values from the YAML front matter. It supports dot notation for nested keys via Arr::get.

    Parameters:

    • ?string $key: The key to retrieve. Supports dot notation (e.g., 'author.name'). If null, returns the entire matter array.
    • mixed $default: The value to return if the key does not exist.
    // Retrieve nested value
$name = $document->matter('author.name', 'Unknown');

// Retrieve top-level value
$date = $document->matter('date');