Spatie Laravel Query Builder

Laravel Query Builder paketi, gelen HTTP isteklerindeki (Query String) parametrelere (?filter[name]=..., ?sort=-created_at, ?include=posts, ?fields[users]=name,email) göre Eloquent sorgularını güvenli, dinamik ve deklaratif bir şekilde filtrelemenizi, sıralamanızı ve ilişkilerini (eager loading) yüklemenizi sağlar. REST API ve zengin arayüzlü tablolar için idealdir.

Neden Tercih Edilmeli?

• JSON:API Standardına Uyum: Filtreleme, sıralama ve alan seçimi için standartlaştırılmış URL parametre sözdizimi sunar.
• Güvenli İzin Listesi (Whitelisting): Sadece izin verdiğiniz (allowedFilters, allowedSorts, allowedIncludes) alanların sorgulanmasına izin vererek SQL injection ve veri ifşasını önler.
• Özel Filtre Sınıfları: Kapsamlı (Exact, Partial, Scope, Callback) özel filtreleme mantıklarını kolayca bağlayabilirsiniz.
• Daha Temiz Controller Kodu: Onlarca satırlık if ($request->has('...')) bloklarını tek bir zincirleme metoda indirger.
• Sayfalama Desteği: Standart Laravel sayfalama (paginate(), cursorPaginate()) metodlarıyla kusursuz çalışır.

Kurulum

Composer ile paketi yükleyin:

composer require spatie/laravel-query-builder

Yapılandırma dosyasını yayınlayabilirsiniz:

php artisan vendor:publish --provider="Spatie\QueryBuilder\QueryBuilderServiceProvider" --tag="query-builder-config"

Temel Kullanım

1. Filtreleme, Sıralama ve İlişki Yükleme

Controller içinde QueryBuilder::for() kullanarak sorguyu inşa edin:

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\User;
use Spatie\QueryBuilder\QueryBuilder;
use Spatie\QueryBuilder\AllowedFilter;
use Illuminate\Http\JsonResponse;

class UserController extends Controller
{
    public function index(): JsonResponse
    {
        $users = QueryBuilder::for(User::class)
            ->allowedFilters([
                'name',
                AllowedFilter::exact('email'),
                AllowedFilter::exact('role_id'),
                AllowedFilter::scope('verified'),
                AllowedFilter::partial('company.name'), // İlişki üzerinden filtreleme
            ])
            ->allowedSorts([
                'name',
                'created_at',
                'updated_at',
            ])
            ->allowedIncludes([
                'posts',
                'company',
                'roles',
            ])
            ->allowedFields([
                'id',
                'name',
                'email',
                'created_at',
            ])
            ->defaultSort('-created_at')
            ->paginate(15);

        return response()->json($users);
    }
}

2. Örnek İstek URL'leri

Artık API uç noktanıza şu istekleri atabilirsiniz:

# İsme göre kısmi filtreleme ve e-postaya göre tam eşleşme:
GET /api/users?filter[name]=tuna&filter[email]=info@example.com

# En yeniden eskiye sıralama:
GET /api/users?sort=-created_at

# İlişkili gönderileri (posts) ve rolleri birlikte getirme (Eager Load):
GET /api/users?include=posts,roles

# Sadece belirli sütunları seçme (Sparse Fieldsets):
GET /api/users?fields[users]=name,email

# Hepsini bir arada kullanma:
GET /api/users?filter[name]=ali&sort=-created_at&include=company&fields[users]=name,email

3. Özel Filtre Tanımlama (Custom Filter)

use Spatie\QueryBuilder\Filters\Filter;
use Illuminate\Database\Eloquent\Builder;

class FilterBetweenDates implements Filter
{
    public function __invoke(Builder $query, $value, string $property)
    {
        $query->whereBetween('created_at', [$value['start'], $value['end']]);
    }
}

// Controller'da kullanım:
QueryBuilder::for(Order::class)
    ->allowedFilters([
        AllowedFilter::custom('date_between', new FilterBetweenDates),
    ]);