bbim/query-scoper

Laravel query scoping library for dynamic filtering

dev-main 2025-09-09 07:36 UTC

Requires

• php: ^8.2
• laravel/framework: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• Bbim Team

• filter
• query
• laravel
• eloquent
• scope

README

A powerful Laravel package for dynamic query filtering and scoping with multiple drivers support.

Features

• 🔍 Dynamic query filtering
• 🎯 Multiple scope drivers
• 📊 Eloquent and Query Builder support
• 🔧 Flexible configuration
• 🧪 Easy testing integration
• 🚀 High performance

Installation

composer require bbim/query-scoper

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="Bbim\QueryScoper\Providers\QueryScoperServiceProvider"

Architecture

Drivers

• EloquentDriver: Manages scopes for Eloquent queries
• QueryBuilderDriver: Manages scopes for Query Builder queries

Scopes

Each scope is a class that extends QueryScoper and implements:

• prepareData(): Extract data from request
• validator(): Validate the data
• prepareBuilder(): Apply conditions to the query

Usage

1. Creating a Scope

<?php

namespace App\Scopes;

use Bbim\QueryScoper\QueryScoper;
use Illuminate\Support\Facades\Validator;

class UserStatusScope extends QueryScoper
{
    protected function prepareData(): array
    {
        return request()->only(['status']);
    }

    protected function validator($data): \Illuminate\Contracts\Validation\Validator
    {
        return Validator::make($data, [
            'status' => 'sometimes|in:active,inactive'
        ]);
    }

    protected function prepareBuilder($builder, $data)
    {
        if (isset($data['status'])) {
            $builder->where('status', $data['status']);
        }

        return $builder;
    }
}

2. Using with Facade

use Bbim\QueryScoper\Facades\QueryScoper;

// Apply specific scopes
$users = QueryScoper::scope(User::query(), [
    UserStatusScope::class,
    DateRangeScope::class
])->get();

3. Using with Trait

use Bbim\QueryScoper\HasScopes;

class UserController extends Controller
{
    use HasScopes;

    public function index()
    {
        $users = $this->scopeToScopes(User::query(), [
            UserStatusScope::class,
            DateRangeScope::class
        ])->get();

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

4. Configuration

Configure your preferred driver in config/query-scoper.php:

'default' => env('QUERY_SCOPER_DRIVER', 'eloquent'),

Examples

ActiveScope

Filters records by status (active/inactive/all)

DateRangeScope

Filters records by date range using from_date and to_date parameters

Benefits

1. Separation of Concerns: Each scope handles one specific filtering logic
2. Reusability: Scopes can be used across different controllers
3. Validation: Built-in validation for scope parameters
4. Flexibility: Easy to add/remove scopes
5. Type Safety: Strong typing with interfaces
6. Simple API: Clean and straightforward usage