Laravel Paper: новий Eloquent-драйвер для роботи з flat-file даними.

Laravel Paper від Jacob Jørgensen переносить функціональність Eloquent на роботу з локальними файлами. Пакет дозволяє працювати з Markdown та JSON як із записами в базі даних. Це зручне рішення для документації, каталогів товарів або невеликих CMS, де використання повноцінної бази даних є зайвим.

# Перетворення файлів на моделі

Завдяки трейту Paper та PHP 8 attributes ви можете прив’язати модель до конкретної директорії на диску. Для початку роботи не потрібно налаштовувати підключення до бази чи запускати migrations:

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;
}

# Запити до файлових даних

Оскільки драйвер реалізує інтерфейс Eloquent, для фільтрації та сортування файлів доступні стандартні методи query builder. Slug автоматично генерується з імені файлу і виступає основним ідентифікатором:

// Отримання всіх сторінок документації для конкретної версії
$docs = Document::where('version', 'v1.0')
    ->orderBy('priority', 'asc')
    ->get();
 
// Отримання конкретної сторінки за назвою файлу
$setup = Document::find('initial-setup');
 
// Пошук у масивах frontmatter або тексті
$tagged = Document::whereContains('labels', 'api')->get();
$found = Document::whereLike('subtitle', '%configuration%')->get();

# Зв’язки між файлами

Пакет дозволяє пов’язувати моделі між собою. Ви можете визначати асоціації на основі полів, що зберігаються у frontmatter ваших файлів:

public function category()
{
    // Визначається за ключем 'category_slug' у Markdown frontmatter
    return $this->belongsToPaper(Category::class);
}
 
public function subPages()
{
    return $this->hasManyPaper(Document::class);
}

# Управління файлами через Eloquent

Laravel Paper підтримує повноцінний запис даних. Методи save() та delete() виконують відповідні операції у файловій системі, синхронізуючи стан контенту з моделлю:

// Створення нового файлу
$doc = new Document();
$doc->slug = 'new-guide';
$doc->title = 'Architecture Overview';
$doc->content = 'Markdown content starts here...';
$doc->save(); // Створює файл content/docs/new-guide.md
 
// Видалення існуючого файлу
$outdated = Document::find('old-api-guide');
$outdated?->delete(); // Видаляє файл із диска

# Встановлення

Пакет встановлюється через Composer:

composer require jacobjoergensen/laravel-paper

Laravel Paper вимагає PHP 8.4 та Laravel 12.0 або новішої версії. Для роботи з Markdown драйвером файли мають містити метадані у форматі YAML frontmatter:

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

Вихідний код та документація щодо створення власних drivers доступні на GitHub.