ervinsvilumsons/laravel-eloquentql

Dynamically optimize Eloquent queries and API resources with JSON:API sparse fieldsets and includes.

v1.0.0 2026-06-17 13:39 UTC

Requires

• php: ^8.4.0

Requires (Dev)

• laravel/pint: ^1.29.1
• orchestra/testbench: ^11.1
• pestphp/pest: ^4.0
• phpunit/phpunit: ^12.3

MIT

• Ervins Vilumsons

• php
• laravel
• eloquent

README

A small Laravel package to extend Eloquent models with JSON:API sparse fieldsets, include relation loading, and resource filtering.

Usage

1. Add the trait to your Eloquent model:

use ErvinsVilumsons\LaravelEloquentQL\Concerns\HasEloquentQL;

class Post extends Model
{
    use HasEloquentQL;
}

1. Use the jsonApi query scope with request input:

$posts = Post::query()
    ->jsonApi()
    ->get();

1. Send JSON:API-style request parameters:

• fields[posts]=title,body
• include=author,comments

This will select only the requested post fields and eager load the requested relationships.

Resource filtering

You can filter resource output so only requested attributes and included relations are returned.

Standard Laravel resource example

use ErvinsVilumsons\LaravelEloquentQL\EloquentQL;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class PostResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        $resource = [
            'id' => $this->id,
            'title' => $this->title,
            'description' => $this->description,
            'author' => new AuthorResource($this->whenLoaded('author')),
        ];

        return EloquentQL::filterResource($resource, 'posts', $request);
    }
}

If the request uses fields[posts]=id,title and include=author, the response will only include id, title, and author.