{"id":15067160,"url":"https://github.com/themustafaomar/laravel-qsw","last_synced_at":"2025-04-10T13:54:39.283Z","repository":{"id":62549793,"uuid":"487751695","full_name":"themustafaomar/laravel-qsw","owner":"themustafaomar","description":"Cleanly apply filters on a query builder depending on query string parameters.","archived":false,"fork":false,"pushed_at":"2024-10-16T07:29:33.000Z","size":9,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T12:39:31.652Z","etag":null,"topics":["laravel","laravel-framework","laravel-package","querystring","scopes"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/themustafaomar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-02T07:18:06.000Z","updated_at":"2024-10-16T07:29:37.000Z","dependencies_parsed_at":"2024-09-29T11:41:19.022Z","dependency_job_id":"78cdf2b0-2117-494c-868d-76ea14939855","html_url":"https://github.com/themustafaomar/laravel-qsw","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themustafaomar%2Flaravel-qsw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themustafaomar%2Flaravel-qsw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themustafaomar%2Flaravel-qsw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themustafaomar%2Flaravel-qsw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/themustafaomar","download_url":"https://codeload.github.com/themustafaomar/laravel-qsw/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248054218,"owners_count":21039951,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["laravel","laravel-framework","laravel-package","querystring","scopes"],"created_at":"2024-09-25T01:17:24.945Z","updated_at":"2025-04-10T13:54:39.266Z","avatar_url":"https://github.com/themustafaomar.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Laravel query-string watcher\n\nCleanly apply filters on a query builder depending on query string parameters.\n\nSometimes 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\u0026with=comments,replies\u0026from=2000-01-10\u0026to=2022-05-25\u0026sort=newest` etc..\n\nThis package makes it easy to accomplish this with a great manner.\n\nThe main goal of using this package is the separation of concerns, we don't want tons of lines in our controllers.\n\n## Installation\n\nYou can install it via [composer](https://getcomposer.org/)\n\n```bash\n$ composer require mustafaomar/laravel-qsw\n```\n\n## Usage\n\nThere are serveral ways to start using `laravel-qsw`\n\n### Scopable trait\n\nYou can use `Scopable` in your model and we're done, you now have access to the `watch` scope, example.\n\nArticle.php\n\n```php\nuse QueryWatcher\\Traits\\Scopable;\n\nclass Article extends Model\n{\n    use HasFactory, Scopable;\n}\n```\n\nThe last step we need is to create a scope, you can do so by using the following command.\n\nFor 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`.\n\n```bash\nphp artisan make:scope ArticleStatusScope\n```\n\nThis command will create a scope class similar to this:\n\n```php\nnamespace App\\Scopes;\n \nuse QueryWatcher\\Contracts\\Scope;\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Illuminate\\Database\\Eloquent\\Builder;\n \nclass ArticleStatusScope implements Scope\n{\n    /**\n     * Apply the scope to a given Eloquent query builder.\n     *\n     * @param \\Illuminate\\Database\\Eloquent\\Builder $builder\n     * @param  \\Illuminate\\Database\\Eloquent\\Model  $model\n     * @return void\n     */\n    public function apply(Builder $builder, Model $model)\n    {\n        //\n    }\n}\n```\n\n## Real-life use cases\n\nNow let's create an example describes how to filter data with real-life example.\n\nArticleController.php\n\n```php\npublic function index(Request $request)\n{\n    $article = Article::watch($this-\u003equeryWatchers())-\u003efirst();\n\n    return response()-\u003ejson($article);\n}\n\nprotected function queryWatchers()\n{\n    return [\n        // 'comments' =\u003e ArticleCommentScope::class,\n        // Notice: sometimes you may want to apply the scope\n        // when two query parameters are presented, you can do this with:\n        'when:from,to' =\u003e ArticleRangeScope::class,\n        'sort' =\u003e ArticleSortScope::class\n    ];\n}\n```\n\nIn this scope, we're gonna filter records which are between a date range.\n\n```php\nclass ArticleRangeScope implements Scope\n{\n    public $from;\n\n    public $to;\n\n    /**\n     * Apply the scope to a given Eloquent query builder.\n     *\n     * @param \\Illuminate\\Database\\Eloquent\\Builder $builder\n     * @param string|number $value\n     * @return void\n     */\n    public function apply(Builder $builder, Model $model)\n    {\n        $builder-\u003ewhereBetween('created_at', [$this-\u003efrom, $this-\u003eto]);\n    }\n}\n\n// Sort scope\n\nclass ArticleSortScope implements Scope\n{\n    public $sort;\n\n    /**\n     * Apply the scope to a given Eloquent query builder.\n     *\n     * @param \\Illuminate\\Database\\Eloquent\\Builder $builder\n     * @param string|number $value\n     * @return void\n     */\n    public function apply(Builder $builder, Model $model)\n    {\n        if ($this-\u003esort === 'newest') {\n            $builder-\u003elatest();\n        } else if ($this-\u003esort === 'oldest') {\n            $builder-\u003eoldest();\n        }\n\n        // ...\n    }\n}\n```\n\n## Advanced\n\nIf for some reasons you don't want to use the `watch` keyword as a scope, you can create your own local `scope`.\n\nin the following example we'll create a scope called `scopes`.\n\nArticle.php\n\n```php\nuse QueryWatcher\\Facades\\QueryWatcher;\nuse Illuminate\\Database\\Eloquent\\Builder;\n\nclass Article extends Model\n{\n    use HasFactory;\n\n    /**\n     * Register the query string params to watch\n     * \n     * @param \\Illuminate\\Database\\Eloquent\\Builder  $builder\n     * @param array  $scopes\n     * @return  \\Illuminate\\Database\\Eloquent\\Builder\n     */\n    public function scopeScopes(Builder $builder, $scopes)\n    {\n        $instance = QueryWatcher::getInstance();\n\n        // Or by resolving query watcher from the container\n\n        $instance = app('laravel.qsw');\n\n        $instance-\u003ewatch($builder, $scopes);\n\n        return $builder;\n    }\n}\n```\n\nPlease 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.\n\n```php\n$article = Article::scopes([])-\u003efirst();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthemustafaomar%2Flaravel-qsw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthemustafaomar%2Flaravel-qsw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthemustafaomar%2Flaravel-qsw/lists"}