PHPackages                             mustafaomar/laravel-qsw - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Search & Filtering](/categories/search)
4. /
5. mustafaomar/laravel-qsw

ActiveLibrary[Search & Filtering](/categories/search)

mustafaomar/laravel-qsw
=======================

Cleanly apply filters on a query builder depending on query string parameters.

v1.1.0(2y ago)3450↓50%MITPHPPHP >=7.2.5

Since May 2Pushed 10mo ago1 watchersCompare

[ Source](https://github.com/themustafaomar/laravel-qsw)[ Packagist](https://packagist.org/packages/mustafaomar/laravel-qsw)[ RSS](/packages/mustafaomar-laravel-qsw/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (1)Versions (4)Used By (0)

Laravel query-string watcher
----------------------------

[](#laravel-query-string-watcher)

Cleanly apply filters on a query builder depending on query string parameters.

Sometimes you may want to apply additional logic on the query builder eg: loading some relationships so you can return that relations with the response depending on the query string parameters, or you may want to apply complex filters eg: `status=active&with=comments,replies&from=2000-01-10&to=2022-05-25&sort=newest` etc..

This package makes it easy to accomplish this with a great manner.

The main goal of using this package is the separation of concerns, we don't want tons of lines in our controllers.

Installation
------------

[](#installation)

You can install it via [composer](https://getcomposer.org/)

```
$ composer require mustafaomar/laravel-qsw
```

Usage
-----

[](#usage)

There are serveral ways to start using `laravel-qsw`

### Scopable trait

[](#scopable-trait)

You can use `Scopable` in your model and we're done, you now have access to the `watch` scope, example.

Article.php

```
use QueryWatcher\Traits\Scopable;

class Article extends Model
{
    use HasFactory, Scopable;
}
```

The last step we need is to create a scope, you can do so by using the following command.

For convention please use the model name followed by the query parameter you want to watch for, followed by Scope, for example `?status=success` will be `ArticleStatusScope`.

```
php artisan make:scope ArticleStatusScope
```

This command will create a scope class similar to this:

```
namespace App\Scopes;

use QueryWatcher\Contracts\Scope;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Builder;

class ArticleStatusScope implements Scope
{
    /**
     * Apply the scope to a given Eloquent query builder.
     *
     * @param \Illuminate\Database\Eloquent\Builder $builder
     * @param  \Illuminate\Database\Eloquent\Model  $model
     * @return void
     */
    public function apply(Builder $builder, Model $model)
    {
        //
    }
}
```

Real-life use cases
-------------------

[](#real-life-use-cases)

Now let's create an example describes how to filter data with real-life example.

ArticleController.php

```
public function index(Request $request)
{
    $article = Article::watch($this->queryWatchers())->first();

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

protected function queryWatchers()
{
    return [
        // 'comments' => ArticleCommentScope::class,
        // Notice: sometimes you may want to apply the scope
        // when two query parameters are presented, you can do this with:
        'when:from,to' => ArticleRangeScope::class,
        'sort' => ArticleSortScope::class
    ];
}
```

In this scope, we're gonna filter records which are between a date range.

```
class ArticleRangeScope implements Scope
{
    public $from;

    public $to;

    /**
     * Apply the scope to a given Eloquent query builder.
     *
     * @param \Illuminate\Database\Eloquent\Builder $builder
     * @param string|number $value
     * @return void
     */
    public function apply(Builder $builder, Model $model)
    {
        $builder->whereBetween('created_at', [$this->from, $this->to]);
    }
}

// Sort scope

class ArticleSortScope implements Scope
{
    public $sort;

    /**
     * Apply the scope to a given Eloquent query builder.
     *
     * @param \Illuminate\Database\Eloquent\Builder $builder
     * @param string|number $value
     * @return void
     */
    public function apply(Builder $builder, Model $model)
    {
        if ($this->sort === 'newest') {
            $builder->latest();
        } else if ($this->sort === 'oldest') {
            $builder->oldest();
        }

        // ...
    }
}
```

Advanced
--------

[](#advanced)

If for some reasons you don't want to use the `watch` keyword as a scope, you can create your own local `scope`.

in the following example we'll create a scope called `scopes`.

Article.php

```
use QueryWatcher\Facades\QueryWatcher;
use Illuminate\Database\Eloquent\Builder;

class Article extends Model
{
    use HasFactory;

    /**
     * Register the query string params to watch
     *
     * @param \Illuminate\Database\Eloquent\Builder  $builder
     * @param array  $scopes
     * @return  \Illuminate\Database\Eloquent\Builder
     */
    public function scopeScopes(Builder $builder, $scopes)
    {
        $instance = QueryWatcher::getInstance();

        // Or by resolving query watcher from the container

        $instance = app('laravel.qsw');

        $instance->watch($builder, $scopes);

        return $builder;
    }
}
```

Please don't get confused with scope and Scopes, `scope` is a word that tells Laravel we want to use the suffixed word (`Scopes`) to call when building a query with the query builder.

```
$article = Article::scopes([])->first();
```

###  Health Score

29

—

LowBetter than 59% of packages

Maintenance38

Infrequent updates — may be unmaintained

Popularity17

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~426 days

Total

2

Last Release

1051d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/586b601d33568807054c09a012583b1e3de0d3140a02756609d95644388159c9?d=identicon)[mustafaomar](/maintainers/mustafaomar)

---

Top Contributors

[![themustafaomar](https://avatars.githubusercontent.com/u/46113191?v=4)](https://github.com/themustafaomar "themustafaomar (6 commits)")

---

Tags

laravellaravel-frameworklaravel-packagequerystringscopes

### Embed Badge

![Health badge](/badges/mustafaomar-laravel-qsw/health.svg)

```
[![Health](https://phpackages.com/badges/mustafaomar-laravel-qsw/health.svg)](https://phpackages.com/packages/mustafaomar-laravel-qsw)
```

###  Alternatives

[mehradsadeghi/laravel-filter-querystring

Filter your queries based on url query string parameters like a breeze.

169118.2k](/packages/mehradsadeghi-laravel-filter-querystring)[pos-lifestyle/laravel-nova-date-range-filter

A Laravel Nova date range filter.

16179.1k](/packages/pos-lifestyle-laravel-nova-date-range-filter)[omure/scout-advanced-meilisearch

Laravel Scout extension that allows to use meilisearch advanced features as well as has an extended collection driver for testing purposes.

123.9k](/packages/omure-scout-advanced-meilisearch)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)