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(3y ago)3487↓88.2%MITPHPPHP >=7.2.5

Since May 2Pushed 1y 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 today

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 57% of packages

Maintenance36

Infrequent updates — may be unmaintained

Popularity18

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity46

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

1099d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/23484701?v=4)[Mustafa Asaad](/maintainers/mustafaomar)[@mustafaomar](https://github.com/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

[unopim/unopim

UnoPim Laravel PIM

10.5k2.4k](/packages/unopim-unopim)[statamic-rad-pack/runway

Eloquently manage your database models in Statamic.

135224.7k7](/packages/statamic-rad-pack-runway)[api-platform/laravel

API Platform support for Laravel

58171.8k14](/packages/api-platform-laravel)[ecotone/laravel

Ecotone for Laravel — CQRS, Event Sourcing, Sagas, Durable Workflows, and Outbox on top of Laravel Queue, via PHP attributes.

21318.6k3](/packages/ecotone-laravel)[duncanmcclean/statamic-cargo

Comprehensive e-commerce addon for Statamic. Build bespoke e-commerce sites without the complexity.

3417.0k](/packages/duncanmcclean-statamic-cargo)

PHPackages © 2026

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