Laravel Paper: محرّك Eloquent مسطّح للتعامل مع الملفات بدل قاعدة البيانات

ماذا لو استطعت استخدام واجهة Eloquent المألوفة في Laravel للتعامل مع ملفات Markdown وJSON على القرص، دون قاعدة بيانات و (migrations) ولا اتصال منفصل؟ هذا بالضبط ما تقدّمه حزمة Laravel Paper، من تطوير Jacob Jørgensen، التي تضيف دعم «المحرك المسطّح» (Flat-file Driver) إلى Eloquent. الفكرة أن تتعامل مع ملفاتك كأنها سجلات في قاعدة بيانات، وهو مثالي للتوثيق، وكتالوجات المنتجات، وأنظمة إدارة المحتوى الصغيرة التي تكون فيها قاعدة البيانات التقليدية عبئًا زائدًا.

تتطلّب الحزمة PHP 8.4 فأحدث وLaravel 12 أو 13، وتعتمد على ميزات PHP 8 الحديثة وتركّز على أمان الأنواع (Type Safety). والأنيق فيها أنها لا تحتاج سوى سمة (Trait) واحدة وخاصيّتين (Attributes) لتحويل أي نموذج إلى نموذج مدعوم بالملفات.

التثبيت

تثبّت الحزمة عبر Composer بأمر واحد:

composer require jacobjoergensen/laravel-paper

تحويل الملفات إلى نماذج

تبدأ بوضع ملفات Markdown في مجلد، ولنقل content/posts/، مع بيانات وصفية في مقدمة الملف (YAML Frontmatter):

---
title: Building a Blog with Flat Files
slug: flat-file-blog
published: true
date: 2024-03-15
tags: [laravel, markdown]
---

Your Markdown content goes here...

ثم تنشئ نموذجًا عاديًا، وتضيف إليه السمة Paper وخاصيّتي Driver وContentPath لتحديد نوع المحرك ومسار الملفات:

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

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

هذا كل شيء. لا اتصال قاعدة بيانات، ولا مخطّط (schema)، ولا هجرات.

الاستعلام عن البيانات

بما أن المحرّك يطبّق واجهة Eloquent، تستطيع استخدام دوال باني الاستعلام (Query Builder) القياسية للتصفية والترتيب تمامًا كأي نموذج آخر:

// جلب كل المنشورات المنشورة مرتّبة بالتاريخ تنازليًا
$posts = Post::where('published', true)
    ->orderBy('date', 'desc')
    ->get();

// البحث بالـ slug
$post = Post::where('slug', 'flat-file-blog')->first();

// التصفية حسب وسم ضمن مصفوفة
$laravelPosts = Post::whereContains('tags', 'laravel')->get();

تتوفّر أيضًا دوال استعلام إضافية مفيدة للمحتوى النصّي مثل whereLike للبحث عن نص جزئي داخل حقل، وwhereAny للبحث عن قيمة عبر عدة حقول دفعة واحدة.

العمل مع ملفات JSON

المنطق نفسه ينطبق على ملفات JSON، ويكفي تغيير نوع المحرّك إلى json. لنفترض ملفًا لعضو فريق:

{
    "name": "Jacob Jørgensen",
    "role": "Developer",
    "github": "jacobjoergensen"
}

#[Driver('json')]
#[ContentPath('content/team')]
class TeamMember extends Model
{
    use Paper;
}

ثم تستعلم عنه كالمعتاد:

$team = TeamMember::all();
$devs = TeamMember::where('role', 'Developer')->get();

تسمية الملفات والمفتاح الأساسي

القاعدة بسيطة وذكية: اسم الملف (بدون الامتداد) يصبح المعرّف الأساسي للنموذج. فمجلد المنشورات التالي:

content/posts/
├── hello-world.md        → id: "hello-world"
├── my-second-post.md     → id: "my-second-post"
└── draft-post.md         → id: "draft-post"

يتيح لك جلب أي منشور مباشرة عبر معرّفه:

$post = Post::find('hello-world');

ولتغيير المعرّف، يكفي إعادة تسمية الملف. وإن أردت رابطًا (URL) مختلفًا عن اسم الملف، تضيف حقلًا في الـ frontmatter وتوجّه المسارات بناءً عليه.

عرض المحتوى في الواجهة

في ملفات Blade، تتعامل مع النماذج كأي مجموعة Eloquent، وتحوّل محتوى Markdown إلى HTML عبر مساعد Laravel القياسي:

@foreach($posts as $post)
    <article>
        <h2>{{ $post->title }}</h2>
        <time>{{ $post->date }}</time>
        <div>{!! Str::markdown($post->content) !!}</div>
    </article>
@endforeach

متى تستخدمها ومتى تتجنّبها؟

Laravel Paper خيار ممتاز حين يكون المحتوى ثابتًا نسبيًا وقابلًا للإصدار عبر Git: مدوّنة، توثيق، صفحات تعريفية، أو كتالوج صغير. ميزتها أنك تحرّر المحتوى كملفات نصّية بسيطة وتتعقّب تغييراته في مستودعك دون الحاجة إلى لوحة تحكّم أو قاعدة بيانات. لكن إن كان مشروعك يتطلّب كتابات متزامنة كثيفة، أو علاقات معقّدة بين آلاف السجلات، أو استعلامات عالية الأداء على بيانات ضخمة متغيّرة باستمرار، فقاعدة البيانات التقليدية تبقى الخيار الأنسب؛ فنظام الملفات لم يُصمَّم لأحمال القراءة والكتابة الكثيفة المتزامنة.

خلاصة

تقدّم Laravel Paper حلًّا أنيقًا ومتوافقًا مع فلسفة Laravel لمشكلة شائعة: إدارة المحتوى الخفيف دون عبء قاعدة بيانات كاملة. بفضل اعتمادها على واجهة Eloquent المألوفة، يصبح منحنى التعلّم شبه معدوم لأي مطوّر Laravel. وكونها حزمة فتية (بإصدارات نشطة في 2026)، يستحسن تجربتها في مشروع جانبي أولًا وقراءة توثيقها الرسمي لمتابعة ما يُضاف من ميزات كعلاقات الملفات وعمليات الكتابة.