Laravel Paper: A Flat-File Eloquent Driver

Laravel Paper, by Jacob Jørgensen, brings Eloquent's feature set to flat-file data sources. It allows you to treat Markdown and JSON files as database records, which is useful for documentation, product catalogs, or small-scale content management where a traditional database might be unnecessary.

#Turning Files into Models

By applying the Paper trait and PHP 8 attributes, you can map a model to a specific directory on your disk. You don't need to configure a separate database connection or run migrations to get started:

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

#Querying File Data

Since the driver implements the Eloquent interface, you can use standard query builder methods to filter and sort your files. The slug is derived from the filename automatically, acting as the primary identifier:

// Fetch all documentation pages for a specific version
$docs = Document::where('version', 'v1.0')
    ->orderBy('priority', 'asc')
    ->get();
 
// Retrieve a specific page by its filename
$setup = Document::find('initial-setup');
 
// Search within frontmatter arrays or text
$tagged = Document::whereContains('labels', 'api')->get();
$found = Document::whereLike('subtitle', '%configuration%')->get();

#File-Based Relationships

The package includes methods for linking different flat-file models. This allows you to define associations based on fields stored in your files' frontmatter:

public function category()
{
    // Resolves based on the 'category_slug' key in the Markdown frontmatter
    return $this->belongsToPaper(Category::class);
}
 
public function subPages()
{
    return $this->hasManyPaper(Document::class);
}

#Managing Files through Eloquent

Laravel Paper supports full write capabilities. When you call save() or delete(), the package performs the corresponding filesystem operation, keeping your content in sync with your model state:

// Creating a new file
$doc = new Document();
$doc->slug = 'new-guide';
$doc->title = 'Architecture Overview';
$doc->content = 'Markdown content starts here...';
$doc->save(); // Creates content/docs/new-guide.md
 
// Deleting an existing file
$outdated = Document::find('old-api-guide');
$outdated?->delete(); // Removes the file from disk

#Installation

You can add the package to your project via Composer:

composer require jacobjoergensen/laravel-paper

Laravel Paper requires PHP 8.4 and Laravel 12.0 or higher. To use the Markdown driver, your files should include YAML frontmatter for metadata:

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

The source code and further documentation for custom drivers are available on GitHub.