Laravel Paper: Dùng Markdown và JSON như Eloquent Models

Không phải mọi dữ liệu trong Laravel đều cần database.

Với những nội dung như documentation, product catalog nhỏ, changelog, static pages hoặc CMS đơn giản, việc tạo bảng, migration và CRUD đôi khi hơi nặng.

Laravel Paper, package của Jacob Jørgensen, giải quyết bài toán này bằng cách đưa trải nghiệm Eloquent vào các nguồn dữ liệu flat-file như Markdown và JSON.

Nói đơn giản: bạn có thể xem file như model.

Laravel Paper là gì?

Laravel Paper cho phép bạn map một Eloquent model vào một thư mục chứa file Markdown hoặc JSON.

Thay vì lưu dữ liệu trong database, bạn có thể lưu trong:

content/docs
content/products
content/pages

Mỗi file trở thành một record.
Filename trở thành slug.
Frontmatter hoặc JSON data trở thành attributes.

Ví dụ một file Markdown:

---
title: Architecture Overview
version: v1.0
labels: [api, core]
priority: 1
---
Markdown content starts here…

File này có thể được query giống như một model Laravel thông thường.

Biến file thành model

Bạn chỉ cần tạo model và dùng trait Paper:

use Illuminate\Database\Eloquent\Model;
use JacobJoergensen\LaravelPaper\Attributes\ContentPath;
use JacobJoergensen\LaravelPaper\Attributes\Driver;
use JacobJoergensen\LaravelPaper\Paper;

#[Driver('markdown')]
#[ContentPath('content/docs')]
class Document extends Model
{
    use Paper;
}

Không cần tạo database connection riêng.
Không cần migration.
Không cần table.

Chỉ cần đặt file vào đúng thư mục là có thể bắt đầu dùng.

Query dữ liệu từ file

Vì Laravel Paper triển khai theo phong cách Eloquent, bạn có thể dùng các method quen thuộc như where, orderBy, get, find.

Ví dụ lấy tài liệu theo version:

$docs = Document::where('version', 'v1.0')
    ->orderBy('priority', 'asc')
    ->get();

Lấy một file theo slug:

$setup = Document::find('initial-setup');

Tìm trong array hoặc text:

$tagged = Document::whereContains('labels', 'api')->get();

$found = Document::whereLike('subtitle', '%configuration%')->get();

Điểm hay là bạn vẫn giữ được workflow quen thuộc của Laravel, nhưng dữ liệu lại nằm trong file.

Relationship giữa các flat-file models

Laravel Paper cũng hỗ trợ relationship giữa các model dạng file.

Ví dụ một document thuộc về một category:

public function category()
{
    return $this->belongsToPaper(Category::class);
}

Hoặc một document có nhiều sub pages:

public function subPages()
{
    return $this->hasManyPaper(Document::class);
}

Relationship có thể dựa trên field trong frontmatter, ví dụ:

category_slug: api

Điều này giúp bạn tổ chức documentation hoặc content system rõ ràng hơn mà không cần database phức tạp.

Ghi và xóa file bằng Eloquent API

Laravel Paper không chỉ đọc file.
Bạn cũng có thể tạo, cập nhật hoặc xóa file thông qua model.

Tạo file mới:

$doc = new Document();

$doc->slug = 'new-guide';
$doc->title = 'Architecture Overview';
$doc->content = 'Markdown content starts here...';

$doc->save();

Khi gọi save(), package sẽ tạo file:

content/docs/new-guide.md

Xóa file:

$outdated = Document::find('old-api-guide');

$outdated?->delete();

Như vậy, bạn có thể quản lý flat-file content bằng API gần giống Eloquent.

Cài đặt Laravel Paper

Cài package qua Composer:

composer require jacobjoergensen/laravel-paper

Laravel Paper yêu cầu:

PHP 8.4+
Laravel 12+

Package hỗ trợ Markdown và JSON. Với Markdown, bạn nên dùng YAML frontmatter để lưu metadata.

Khi nào nên dùng Laravel Paper?

Laravel Paper phù hợp với:

• Documentation

• Product catalog nhỏ

• Blog kỹ thuật

• Changelog

• Static content pages

• Small CMS

• Nội dung cần quản lý bằng Git

Đây là lựa chọn tốt khi dữ liệu của bạn đơn giản, ít thay đổi và gần với “content file” hơn là dữ liệu nghiệp vụ.

Khi nào không nên dùng?

Không nên dùng Laravel Paper cho:

• Order

• Payment

• User account

• Inventory realtime

• Chat message

• Analytics data

• Dữ liệu ghi liên tục

• Dữ liệu cần transaction

Với các hệ thống có dữ liệu lớn, nhiều quan hệ phức tạp hoặc nhiều user ghi cùng lúc, database truyền thống vẫn là lựa chọn đúng hơn.

Kết luận

Laravel Paper là một package rất đáng chú ý cho Laravel developer muốn quản lý content bằng file nhưng vẫn giữ trải nghiệm Eloquent.

Bạn có thể dùng Markdown và JSON như model, query bằng các method quen thuộc, định nghĩa relationship và thậm chí save/delete file thông qua API gần giống Eloquent.

Nếu bạn đang xây documentation, catalog nhỏ hoặc content system đơn giản trong Laravel, Laravel Paper là package rất đáng thử.