README

Fusion

Fusion 是一个 Laravel 扩展包，旨在通过 Eloquent 模型管理 Markdown 内容，无需传统数据库设置。它通过利用带有 Frontmatter 的 Markdown 文件实现这一点。

Fusion 通过整合 Markdown 和 Frontmatter 的力量，帮助网站开发，使开发者能够创建内容驱动的网站，而无需管理数据库。

使用 Fusion，开发者可以利用 Markdown 语法的简单性和 Frontmatter 的灵活性，无缝地组织结构化内容。

通过将 Frontmatter 解析为 Eloquent 模型，Fusion 使开发者能够轻松创建复杂的结构化网站。与数据库管理的复杂性说再见，欢迎使用 Fusion 的简化网站开发。

警告

该包处于开发中（版本 0.0.x），因此提供的功能、类和方法可能会更改，特别是对于 FusionBaseModel 模型类。因此，如果您想开始使用该包以提供反馈，欢迎，但请勿在生产环境中使用，直到 1.0.0 版本发布。谢谢。

安装

您可以通过 composer 工具安装此包

composer require hi-folks/fusion

用法

安装 Fusion 后，您可以开始创建 Markdown 文件中的内容，并通过模型查询文件。例如，现在我们将以 Markdown 格式创建文章，并将解析和查询它们，就像您处理数据库一样。

创建内容

在 resources/content 目录中，您可以创建 article 目录。在 resources/content/article 中，您可以创建带有 Frontmatter 标头的 Markdown 文件，例如

---
date: 2024-04-05
title: Example title for article 1
excerpt: This will be a short excerpt from article number 1.
published: true
---

# Article 1

Markdown goes here

您可以将此文件命名为 resources/content/article/article-1.md 您可以创建类似的其他 Markdown 文件。这些文件代表您的文章。

创建模型

类似于您在数据库中做的，您可以为加载 Markdown 文件创建模型。因为您正在创建文章，所以您可以将模型创建为 app/Models/Article.php。

您可以这样填写文件

<?php

namespace App\Models;


use HiFolks\Fusion\Models\FusionBaseModel;
use HiFolks\Fusion\Traits\FusionModelTrait;

class Article extends FusionBaseModel
{
    use FusionModelTrait;


    public function frontmatterFields(): array
    {
        return [
            "excerpt"
        ];
    }

}

请注意

该类必须使用 extends FusionBaseModel 扩展 FusionBaseModel；
您必须使用 FusionModelTrait 特性： use FusionModelTrait;
您必须实现 frontmatterFields() 函数以返回 Frontmatter 标头中使用的字段名称列表。

自动创建模型

如果您想根据 Markdown 文件的结构和内容自动创建模型文件，可以使用 fusion:sync-model 命令

php artisan fusion:sync-model --path=resources/content/project --create-model

path 参数设置特定模型的 Markdown 文件目录（如文章、页面、帖子、项目等）。--create-model 选项将根据 Markdown 文件的内容和 Frontmatter 部分自动生成模型文件。如果没有 --create-model 选项，fusion:sync-model 命令将列出从 Markdown 中检测到的某些信息，例如模型名称和字段列表。

查询内容

现在在您的控制器或 Blade 组件中，您可以使用 Article 模型，使用通常的方法，如 where()、orderBy() 等。

$articles = \App\Models\Article
    ::where('published', true)
    ->orderBy('date')
    ->get();

高级用法

一旦您掌握了使用 Fusion 与 Markdown 文件的基本方法，您就可以使用一些高级功能。考虑到 Fusion 是一个 Laravel 扩展包，在设计与实现该扩展包时，我们尽可能地利用并遵循 Laravel 的功能。采用这种方法，我们相信我们可以继承一些 Laravel 功能的所有优势。以下章节中我们将探索和解释的一些功能包括

在浏览器中重新加载您正在查看的网站的页面，当您更改 Markdown 内容时；
在模型中将日期转换为字符串，以便您可以在 Frontmatter 标题中使用日期；
在模型中将集合转换为字符串，以便您可以使用复杂和嵌套的 Frontmatter 标题；
使用“检查 Markdown”命令来检测 Markdown 文件中的 Frontmatter 字段。

添加实时页面刷新

如果您希望在更改 Markdown 文件中的某些内容时浏览器自动刷新页面，您可以在 laravel Vite 插件中设置 refresh 选项。在 vite.config.js 文件中添加 refresh 选项，并指定您希望 Vite 监视以进行更改并刷新页面的文件夹列表。

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: ["resources/css/app.css", "resources/js/app.js"],
            refresh: [
                {
                    paths: ["resources/content/**"],
                },
            ],
        }),
    ]
});

在示例中，已添加 resources/content 目录。

如果您需要设置 Vite 资产打包，可以查看 Laravel 文档：https://laravel.net.cn/docs/11.x/vite

在 Markdown 文件中使用日期

如果您想在 Frontmatter 中使用日期（或日期时间），可以在 Frontmatter 中使用 YYYY-MM-DD 格式，例如

---
date: 2023-01-26
title: Example title for article 1
---
This is the **Markdown**.

然后在模型中您可以这样设置转换

    protected function casts(): array
    {
        return [
            'date' => 'datetime:Y-m-d',
        ];
    }

其中 date 是字段名称，与您在 Markdown 中使用的名称相同。

如果您正在添加新字段，请记住在模型中的 frontmatterFields() 函数的字段列表中添加字段名称

    public function frontmatterFields(): array
    {
        return [
            "title", "date", "excerpt", "published", "highlight", "head"
        ];
    }

如果您想进一步了解 Laravel 模型的属性转换，可以查看 Laravel Eloquent 属性转换文档。

在 Markdown 文件中使用集合

如果您需要在 Markdown 中管理复杂数据，例如标签列表，您可以在 Frontmatter 中使用数组

---
date: 2023-01-26
title: Example title for article 1
excerpt: This will be a short excerpt from article number 1.
published: true
highlight: true
head:
  - tag: title
    content: Custom about title
  - tag: title2
    content: Custom about title2
---

# Article 1

Markdown goes here

例如，我们正在添加一个名为 head 的字段，该字段是标签和内容的值数组。

在模型文件中，您必须将 head 字段正确转换为 collection。

    protected function casts(): array
    {
        return [
            'head' => 'collection',
            'date' => 'datetime:Y-m-d',
        ];
    }

这样，在您的 blade 文件中，您可以遍历 head 字段并访问 tag 或 content 子字段

@if (! is_null($article->head))
    @foreach ($article->head as $headItems)
    <div class="mx-3 px-8 badge badge-neutral">{{ $headItems["tag"] }}</div>
    @endforeach
@else
    <div class="mx-3 px-8 badge badge-ghost">No Tag</div>
@endif

自定义 slug

默认情况下，内容的 slug 是不带扩展名的文件名。现在您可以使用 Frontmatter 属性 slug 来自定义 slug。例如

---
date: 2023-04-13
slug: fusion
name: Fusion
claim:  build Website with Markdown files
excerpt: Fusion integrates Markdown into Laravel Models, simplifying Website development.
published: true
highlight: true
image: /img/fusion-cover-website.webp
tags:
  - tag: Laravel
  - tag: Website Development
---

# Fusion

Fusion aids in website development by integrating the power of Markdown and Frontmatter, enabling developers to create content-driven Web sites without having to manage databases.

使用“检查 Markdown”命令

要检查 Markdown 文件并显示和列出 Frontmatter 字段，可以使用 Artisan 命令 fusion:check。

php artisan fusion:check

使用“检查模型”命令

要检查模型文件并确认它是否扩展了正确的类并使用了适当的特质以与 Markdown 文件兼容，可以使用 fusion:check-model 命令

php artisan fusion:check-model --model="App\Models\Article"

输出将告诉您您的模型是否正确

Parsing the Model File
Class App\Models\Article exists
App\Models\Article extends correctly the class HiFolks\Fusion\Models\FusionBaseModel
App\Models\Article uses HiFolks\Fusion\Traits\FusionModelTrait

测试

composer test

变更日志

有关最近更改的更多信息，请参阅 CHANGELOG。

贡献

有关详细信息，请参阅 CONTRIBUTING。

安全性

如果您发现任何与安全相关的问题，请使用“新建问题”功能在跟踪器中打开一个问题（点击此处）。

鸣谢

许可证

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

参考

我们使用了一些优秀且强大的开源库来构建这个开源项目，例如

Sushi：Eloquent缺失的"数组"驱动程序；
league/commonmark：高度可扩展的PHP Markdown解析器，完全支持CommonMark和GFM规范；
yaml-front-matter：一个简洁的yaml front matter解析器；
PestPHP：Pest是一个优雅的PHP测试框架，注重简洁性，精心设计以恢复PHP测试的乐趣。在底层，PestPHP使用PHPUnit，PHP测试框架；
RectorPHP：PHP 5.3+代码的即时升级和自动化重构；
Laravel Pint：一个针对极简主义者定制的PHP代码风格修复工具。在底层，Laravel Pint使用PHP-CS-Fixer开源工具自动修复PHP编码标准问题。

Laravel包模板

此包是使用Laravel包模板生成的。

hi-folks / fusion

维护者

详细信息