Laravel Paper

Laravel Paper is a Laravel package that adds flat-file driver support for Eloquent. It supports Markdown and JSON files and works with Laravel 12+ on PHP 8.4+.

Why Laravel Paper?

Two PHP 8 attributes and a trait. No custom database connection, no schema, your flat files use Eloquent's familiar query API.

Get Started

composer require jacobjoergensen/laravel-paper

Defining a Model

Put files in a content directory and point a model at it:

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

The filename without extension becomes the slug, which is the primary key.

Markdown Example

A post:

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

Your Markdown content goes here...

Query it like any other Eloquent model:

// Get all published posts
$posts = Post::where('published', true)
    ->orderBy('date', 'desc')
    ->get();

// Find by slug
$post = Post::where('slug', 'flat-file-blog')->first();

// Filter by tag (whereContains checks membership of an array field)
$laravelPosts = Post::whereContains('tags', 'laravel')->get();

// Match a substring in a string field
$intro = Post::whereLike('title', '%hello%')->get();

// Search a value across multiple columns
$results = Post::whereAny(['title', 'content'], 'like', '%flat-file%')->get();

Use it in your views:

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

JSON Files

Works the same way with 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();

File Naming and Slugs

The filename (without extension) is the slug:

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

$post = Post::find('hello-world');
$posts = Post::findMany(['hello-world', 'my-second-post']);

To change a slug, rename the file. For a URL that differs from the filename, add a frontmatter field and route on that instead:

---
title: Hello World
permalink: /blog/2024/hello-world
---

Writing

Paper models save and delete files using the standard Eloquent API:

$post = new Post();
$post->slug = 'hello-world';
$post->title = 'Hello World';
$post->content = 'My first post.';
$post->save();

$post->title = 'Updated title';
$post->save();

$post->delete();

Save and delete fire the usual model events, and loading a record fires retrieved.

For attribute-array creation:

Post::create([
    'slug' => 'hello-world',
    'title' => 'Hello World',
]);

Post::firstOrCreate(
    ['slug' => 'hello-world'],
    ['title' => 'Hello World'],
);

Post::updateOrCreate(
    ['slug' => 'hello-world'],
    ['title' => 'Updated title'],
);

For bulk edits, update sets values across every matching record:

Post::where('draft', true)->update(['published' => true]);

It writes each matching file in a loop, so model events fire per record and $fillable does not apply. It is not a single atomic operation.

To save or delete without firing events:

$post->saveQuietly();
$post->deleteQuietly();

To reload from disk, fresh() returns a new instance and refresh() updates the current one in place:

$fresh = $post->fresh();
$post->refresh();

Timestamps

Paper models have no timestamps by default. Add #[Timestamps] to expose the file's modification time as updated_at:

use JacobJoergensen\LaravelPaper\Attributes\Timestamps;

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

$post = Post::find('hello-world');
$post->updated_at;                          // Carbon instance from the file's mtime

$recent = Post::latest('updated_at')->get();

updated_at comes from the file's mtime and is never written to frontmatter. created_at isn't derived; set it in frontmatter if you need it. A Git checkout resets mtimes to the deploy time, so use this for content edited in place and keep a frontmatter date for Git-deployed content.

Pagination

$posts = Post::paginate(15);
$posts = Post::simplePaginate(15);

Use simplePaginate for large directories where the count is expensive, and you don't need a total.

Relationships

For relationships, use belongsToPaper and hasManyPaper:

class Post extends Model
{
    use Paper;

    public function author()
    {
        return $this->belongsToPaper(Author::class);
    }
}

class Author extends Model
{
    use Paper;

    public function posts()
    {
        return $this->hasManyPaper(Post::class);
    }
}

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

$author = Author::find('jane-doe');
$posts = $author->posts();

Call these as methods, not properties. Foreign keys default to {model}_slug (e.g. author_slug). Pass a second argument to override.

Validation

Use PaperRule with Laravel's validator:

use JacobJoergensen\LaravelPaper\Rules\PaperRule;

$request->validate([
    'slug' => ['required', PaperRule::unique(Post::class)],
    'author_slug' => ['required', PaperRule::exists(Author::class)],
]);

To skip the current record on update:

PaperRule::unique(Post::class)->ignore($post->slug);

Custom Drivers

Markdown and JSON ship by default. To support another format, implement DriverContract and register it in a service provider:

use JacobJoergensen\LaravelPaper\Contracts\DriverContract;
use JacobJoergensen\LaravelPaper\Drivers\DriverRegistry;

final class YamlDriver implements DriverContract
{
    public function extensions(): array
    {
        return ['yaml', 'yml'];
    }

    public function parse(string $filepath): array
    {
        // return the file's data as an array
    }

    public function serialize(array $data): string
    {
        // return the file contents to write
    }
}

public function boot(): void
{
    app(DriverRegistry::class)->register('yaml', YamlDriver::class);
}

Then point a model at it with #[Driver('yaml')].

Contributing

See CONTRIBUTING.md for filing bugs and submitting PRs.

License

MIT. See LICENSE.