daylerees / kurenai

Kurenai is a document with metadata parsing library for PHP.

Kurenai

Kurenai is a document with metadata parsing library for PHP. It supports a variety of different document content and metadata parsers.

---

Installation

Kurenai is available on Packagist for Composer.

composer require daylerees/kurenai

Usage

Kurenai documents look like this:

Some form of metadata here.
===
Some form of content here.

A metadata section, and a content section seperated by three equals === signs or more.

Here's an example using JSON for metadata, and Markdown for content.

{
    "title": "Hello world!"
}
===
# Hello World

Well hello there, world!

Formats for metadata and content are interchangable using classes called parsers. First, let's create our parser instance.

$kurenai = new \Kurenai\Parser(
    new \Kurenai\Parsers\Metadata\JsonParser,
    new \Kurenai\Parsers\Content\MarkdownParser
);

In the above example, we're using a JSON metadata parser, and a Markdown content parser. We can now parse a document.

$document = $kurenai->parse('path/to/document.md');

Our documents can have any filename or extension. You can also pass the parse() function the content of a document directly.

The document instance has a few useful methods.

$document->getRaw();

This will fetch the raw document content. Before Kurenai parsed it.

$document->getMetadata();

This will fetch the metadata, parsed into an array.

$document->getContent();

This will get the content of the document, rendered using the provided content parser.

$document->get('foo.bar');

The get() method uses dot-notation to return a metadata value. For example, the above example would be equivalent to fetching $metadata['foo']['bar'].

If the subject can't be found, null will be returned. You can supply a default value as a second parameter to the method.

Metadata Parsers

Format	Install Package	Class
JSON	N/A	Kurenai\Parsers\Metdata\JsonParser
YAML	symfony/yaml	Kurenai\Parsers\Metdata\YamlParser
INI	N/A	Kurenai\Parsers\Metdata\IniParser

Content Parsers

Format	Install Package	Class
Plaintext (no parsing)	N/A	Kurenai\Parsers\Content\PlainTextParser
CommonMark	league/commonmark	Kurenai\Parsers\Content\CommonMarkParser
Markdown	michelf/php-markdown	Kurenai\Parsers\Content\MarkdownParser
Markdown Extra	michelf/php-markdown	Kurenai\Parsers\Content\MarkdownExtraParser
Parsedown (Github Markdown)	erusev/parsedown	Kurenai\Parsers\Content\ParsedownParser
Textile	netcarver/textile	Kurenai\Parsers\Content\TextileParser

Enjoy using Kurenai!

kurenai's Issues

Suggestions?

Hi @daylerees,
It is very funny I was working on something similar and I just discovered your repository.

May I bring some suggestions?

When you parse the document for metadata, why don't you use use Symfony\Component\Yaml\Yaml; and then something like Yaml::parse($metadata);. With that we will end with a similar key => `value' (multidimensional) array and you bring the power of Yaml inside your package which means we can put even more structured metadata.

My code looks like the following.

---
title: foo
slug: bar
tags: [foo, bar, baz]
related:
    - foo: bar
      baz: doo

---
@
# My markdown content
@

Then I extract the content with:

    /**
     * Extract content inside delimiters.
     *
     * @param string $start
     * @param string $end
     * @return string Extracted content.
     *
     * @source
     * http://www.bitrepository.com/extract-content-between-two-delimiters-with-php.html
     */
    protected function extract_unit($string, $start, $end)
    {
        $pos        = stripos($string, $start);
        $str        = substr($string, $pos);
        $str_two    = substr($str, strlen($start));
        $second_pos = stripos($str_two, $end);
        $str_three  = substr($str_two, 0, $second_pos);

        return trim($str_three);
    }

But I admit I feel stupid because in your code you don't even need to use delimiter for the markdown content... I will dig in your code to see how you do the magic.

Then, once I have extracted the content between --- I simply parse it with: return Yaml::parse($this->extract_unit($content, '---', '---')); and voila.

What do you think about it and the use of Yaml?

Add php 5.4 dependency in composer.json

This "package" can't be used in php 5.3 because the DocumentParser class uses "callable" type hint, that is present in php >= 5.4.

I manually removed the type hint to could use it in a production server, but if you don't want to support php 5.3 I'll recomment to add a "note" in the readme.md or add it to composer dependency.

(I'm Spanish, sorry for my English!)

Regards and thnaks for this package! 👍

Typo in documentation on kurenai.readme.io

On https://kurenai.readme.io/docs/parsing-documents it is written:

$document->getMetdata(); // Get document metadata as array.

There is a typo: getMetdata --> getMetadata

Notice for use of list function

Here is the error:

Notice: Undefined offset: 1 in /vendor/daylerees/kurenai/src/Parser.php on line 58

I assume that is for a wrong use of list php function.

Support for Laravel blade templates

Have you considered writing an extended Laravel ViewFactory, that would first parse all blade templates for metadata before handing the content back to Laravel for normal handling?

I can think of a number of cases where I might want to allow views to offer up some config, and access that in the controller.

public function myControllerFunction()
{
    $view = view('my.page');
    if($view->getMetadata()['foo'] == 'bar') {
        doSomething();
    }

    return $view;
}

my/page.blade.php:

{
    "foo": "bar"
}
===
@extends('layouts.main')
@section('content')
    The rest of my normal blade template
@endsection