README

[WIP] Frontmatter Jekyll 风格解析器

可用解析器

• yaml（使用 symfony/yaml）
• Markdown（使用 erusev/parsedown-extra）
• Json（使用 seld/jsonlint）

安装

通过 Composer

$ composer require devster/frontmatter

并且添加内置解析器所使用的额外包

# YAML
$ composer require symfony/yaml

# Markdown
$ composer require erusev/parsedown-extra

# Json
$ composer require seld/jsonlint

这些包不是默认必需的，以最小化占用空间并加快安装速度，如果您只需要其中几个

使用方法

基本使用

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

$parser = new Devster\Frontmatter\Parser('yaml', 'markdown');
$content = <<<EOF
---
title: My Content
description: "This is a description"
---
This is *Markdown* content
EOF;

$frontmatter = $parser->parse($content);

echo $frontmatter->head['title']; // My content
echo $frontmatter->getBody(); // This is <em>Markdown</em> content

由于 frontmatter 格式不仅被开发者使用，因此此解析器相当宽容

上述所有内容示例都像正常 frontmatter 内容一样被解析

$content = <<<EOF
    --- title: My Title ---
# Title 1

## Title 2
EOF;

$content = <<<EOF

 ---
   title: My Title ---

# Title 1

## Title 2
EOF;

仅解析 frontmatter，不处理头部和主体

$p = new Parser;
$result = $p->parseFrontmatter($content);

echo $result['head'];
echo $result['body'];

自定义 frontmatter 分隔符

$p = new Parser('json', 'markdown', '##');
$p->parse(<<<EOF
##
{ "title": "My title" }
##
Body content
EOF);

// You can also let your user use its own delimiter
$p = new Parser;
$p
    ->guessDelimiter()
    ->parse(<<<EOF
~~X~~
head
~~X~~
body
EOF);

从文件名猜测解析器

根据扩展名，可以从文件名猜测 frontmatter 解析器

以下是一些示例

• my_file.json.md：头部使用 Json，主体使用 Markdown
• my_file.md：头部将使用构造函数中设置的解析器进行解析，主体在 Markdown 中
• my_file.unknown：将抛出异常
• my_file.yml.unknown：将抛出异常

$p = new Parser;
$p
    ->guessParsersFromFilename('my_file.yml.md')
    ->parse(file_gets_content('my_file.yml.md'))
;

// Or you can set the default head parser

$p = new Parser('json');
$p
    ->guessParsersFromFilename('my_file.md')
    ->parse(file_gets_content('my_file.md'))
;

从头部猜测主体解析器

您也可以在头部中明确指定应该使用哪个解析器来解析主体。

$p = new Parser('yaml');
$p
    ->guessBodyParserFromHead('[options][format]')
    ->parse(<<<EOF
---
title: My Title
options:
    format: json
---
{
    "body": "This is my body"
}
EOF);

内部使用 symfony 的 Property Access 组件。请参阅其文档以找到从头部获取解析器的路径

如果无法从头部获取解析器，则将使用默认的主体解析器。

更复杂的使用

$p = new Devster\Frontmatter\Parser('yml', 'md');
$p
    ->guessDelimiter()
    ->guessParsersFromFilename('my_file.md')
    ->guessBodyParserFromHead('[format]')
;

try {
    $p->parse($content);
} catch (Devster\Frontmatter\Exception\Exception $e) {
    if ($e instanceof Devster\Frontmatter\Exception\ParserNotFoundException) {
        // The head or the body parser is not found
    }

    if ($e instanceof Devster\Frontmatter\Exception\ParsingException) {
        // Unable to parse the frontmatter content
        // or
        // an error occured in head or body parsing
    }
}

测试

$ vendor/bin/phpunit

路线图

• 将头部重命名为 header
• 添加 INI 解析器
• 允许不解析主体，以避免创建新的自定义解析器，如果需要不是内置的
• 添加验证功能
• 添加转储功能

贡献

请参阅 CONTRIBUTING 获取详细信息。

致谢

特别感谢 Etienne Zannelli 对正则表达式的帮助 ❤

• 所有贡献者

许可

MIT 许可证（MIT）。请参阅 许可文件 获取更多信息。