PHPackages                             mobileka/scope-applicator - 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. mobileka/scope-applicator

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

mobileka/scope-applicator
=========================

Scope Applicator is a PHP trait that makes data filtering and sorting easy.

1.1.2(10y ago)251.2k12MITPHPPHP >=5.4.0

Since Feb 21Pushed 9y ago5 watchersCompare

[ Source](https://github.com/mobileka/scope-applicator)[ Packagist](https://packagist.org/packages/mobileka/scope-applicator)[ RSS](/packages/mobileka-scope-applicator/feed)WikiDiscussions master Synced 6d ago

READMEChangelogDependencies (4)Versions (6)Used By (2)

[![Build Status](https://camo.githubusercontent.com/fb8e23e1bfbec09deffae20cd3491badf555fd685faf7145cb8f2c3e43623ecf/68747470733a2f2f7472617669732d63692e6f72672f6d6f62696c656b612f73636f70652d6170706c696361746f722e737667)](https://travis-ci.org/mobileka/scope-applicator)[![Code Climate](https://camo.githubusercontent.com/c88b591aea817fb1c630417fd28004662c552a89462ce0576abd45a6c6d811ff/68747470733a2f2f636f6465636c696d6174652e636f6d2f6769746875622f6d6f62696c656b612f73636f70652d6170706c696361746f722e737667)](https://codeclimate.com/github/mobileka/scope-applicator)[![Coverage Status](https://camo.githubusercontent.com/51085efea01aaf5c649d84b453f7f5880612839742fcde59f7dfdb6198c4e439/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6d6f62696c656b612f73636f70652d6170706c696361746f722f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/r/mobileka/scope-applicator?branch=master)

ScopeApplicator brings an elegant way of sorting and filtering data to your PHP projects.

- [Overview](#overview)
- [Requirements](#requirements)
- [Installation](#installation)
- [Supported frameworks](#supported-frameworks)
- [Usage](#usage)
- [Configuration options](#configuration-options)
    - [Alias](#alias)
    - [Type](#type)
    - [Default](#default)
    - [Allow Empty](#allow-empty)
    - [Keys (experimental)](#keys-experimental)
- [Credits](#credits)
- [Contributing](#contributing)
- [License](#license)

Overview
--------

[](#overview)

ScopeApplicator is an easy, logical and framework-agnostic way to achieve something like this:

`/posts` – returns a list of all posts

`/posts?recent` – returns only recent posts

`/posts?author_id=5` – returns posts belonging to an author with an `id=5`

`/posts?author_id=5&order_by_title=desc&status=active` – returns only active posts belonging to an author with an `id=5` and sorts them by a title in a descending order

Requirements
------------

[](#requirements)

— php >= 5.4

Supported frameworks:
---------------------

[](#supported-frameworks)

- [Laravel ~5.1](https://github.com/mobileka/scope-applicator-laravel) ([documentation](https://github.com/mobileka/scope-applicator-laravel/blob/master/readme.md))
- [Laravel 5.0.x](https://github.com/mobileka/scope-applicator-laravel/tree/laravel_4_and_5.0) ([documentation](https://github.com/mobileka/scope-applicator-laravel/blob/laravel_4_and_5.0/readme.md))
- [Laravel 4.x.x](https://github.com/mobileka/scope-applicator-laravel/tree/laravel_4_and_5.0) ([documentation](https://github.com/mobileka/scope-applicator-laravel/blob/laravel_4_and_5.0/readme.md))
- [Laravel 3.x.x](https://github.com/mobileka/scope-applicator-laravel/tree/laravel_4_and_5.0) ([documentation](https://github.com/mobileka/scope-applicator-laravel/blob/laravel_4_and_5.0/readme.md))
- [Yii 2.0.x](https://github.com/mobileka/scope-applicator-yii2) ([documentation](https://github.com/mobileka/scope-applicator-yii2/blob/master/readme.md))

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

[](#installation)

If you're using one of the [supported frameworks](#supported-frameworks), follow framework-specific installation instructions on its page.

Otherwise, you can install ScopeApplicator as follows:

`composer require mobileka/scope-applicator 1.1.*`

Usage
-----

[](#usage)

If you're using one of the [supported frameworks](#supported-frameworks), follow framework-specific usage instructions on its page.

Otherwise, you have to create a custom binding for your own framework or PHP-project.

*TODO: add detailed instructions about bindings*

Configuration options
---------------------

[](#configuration-options)

ScopeApplicator supports several configuration options and these are described in this chapter.

#### Alias

[](#alias)

Sometimes we don't want our users to see the actual scope name. Alias is a key that maps a URL query parameter to a scope name.

Example:

```
public $scopes = [
    'orderByTitle' => ['alias' => 'order_by_title']
];
```

`/posts?order_by_title` – an `orderByTitle` scope will be applied

`/posts?orderByTitle` – no scope will be applied

#### Type

[](#type)

This option allows to cast a type of a parameter value before it will passed to a scope.

When type is set to `bool` or `boolean`, only `1` and `true` will be converted to `true`. Everything else is considered to be `false`.

If `type` is set to something different than `bool` or `boolean`, `settype` php function will be called.

Examples:

```
public $scopes = [
    'userId' => [
        'alias' => 'author_id',
        'type' => 'int'
    ],
    'new' => [
        'type' => 'bool'
    ]
];
```

`/posts?author_id=123sometext555` – a `userId` scope will be applied with integer `123` as an argument

`/posts?new=true` – a `new` scope will be applied with boolean `true` as its argument

`/posts?new=yes` – a `new` scope will be called with boolean `false` as its argument

#### Default

[](#default)

When this option is set, a scope will be applied on every single request, even when there are no query parameters in URL matching a scope name or alias.

Examples:

```
public $scopes = [
    'userId' => [
        'alias' => 'author_id',
        'default' => 5
    ]
];
```

`/posts?author_id=1` - a `userId` scope will be applied with `1` as an argument

`/posts` - a `userId` scope will be applied with `5` as an argument

#### Allow Empty

[](#allow-empty)

`allowEmpty` is used when an empty string should be passed to a scope as an argument. This option is set to `false` by default, so the empty string *won't* be passed to a scope.

Examples:

```
public $scopes = [
    'userId' => [
        'alias' => 'author_id',
        'allowEmpty' => true
    ]
];
```

`/posts?author_id` – a `userId` scope will be applied with `''` (empty string) as an argument.

> Please note that when `allowEmpty` is set to `false` (what is a default behavior), you always have to provide a default value for the scope argument. Otherwise, the "Missing argument" exception will be thrown when `/posts?author_id` route is being hit.

> Also note that when `allowEmpty` is set to `true`, a default value of a scope argument will be ignored and an empty string will be passed instead.

#### Keys (experimental)

[](#keys-experimental)

Keys are used when a scope accepts multiple arguments.

Example:

```
public $scopes = [
    'createdAt' => [
        'alias' => 'created_at',
        'keys' => ['from', 'to']
    ]
];
```

`/posts?created_at[from]=000-00-00&created_at[to]=2014-07-23` – a `createdAt` scope will be applied with `'0000-00-00'` as a first argument and `'2014-07-23'` as a second

> Please note that I don't recommend using this right now as it's an experimental feature. Create two separate scopes instead (`createdAtFrom` and `createAtTo`) until this feature is marked as "stable".

Credits
-------

[](#credits)

Scope Applicator is inspired by [has\_scope](https://github.com/plataformatec/has_scope) Ruby gem.

Contributing
------------

[](#contributing)

If you have noticed a bug or have suggestions, you can always create an issue or a pull request (use PSR-2). We will discuss the problem or a suggestion and plan the implementation together.

License
-------

[](#license)

ScopeApplicator is an open-source software and licensed under the [MIT License](https://github.com/mobileka/scope-applicator/blob/master/license).

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity24

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity62

Established project with proven stability

 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 ~106 days

Total

5

Last Release

3678d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/bf96f7b7ef86ec5311f2f860ea1549a855ba0a3e3b81c683363ee1b4614058b8?d=identicon)[mobileka](/maintainers/mobileka)

---

Top Contributors

[![mobileka](https://avatars.githubusercontent.com/u/1132388?v=4)](https://github.com/mobileka "mobileka (28 commits)")

---

Tags

laravelyiifilteringfiltersscopes

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/mobileka-scope-applicator/health.svg)

```
[![Health](https://phpackages.com/badges/mobileka-scope-applicator/health.svg)](https://phpackages.com/packages/mobileka-scope-applicator)
```

###  Alternatives

[indexzer0/eloquent-filtering

Powerful eloquent filtering

22425.9k3](/packages/indexzer0-eloquent-filtering)[millat/laravel-hooks

The WordPress filter, action system in Laravel

5715.1k](/packages/millat-laravel-hooks)[kalfheim/sanitizer

Data sanitizer for PHP with built-in Laravel support.

1423.7k](/packages/kalfheim-sanitizer)[omaressaouaf/query-builder-criteria

Define reusable query criteria for filtering, sorting, search, field selection, and includes in Laravel Eloquent models

282.4k](/packages/omaressaouaf-query-builder-criteria)[kirschbaum-development/livewire-filters

Livewire Filters is a series of Livewire components that provide you with the tools to do live filtering of your data from your own Livewire components.

164.1k](/packages/kirschbaum-development-livewire-filters)[swishdigital/faceted-navigation

Provides faceted navigation of entries, using categories, which allows site users to narrow the list of entries they see by applying multiple filters (think Amazon or eBay left sidebar).

152.4k](/packages/swishdigital-faceted-navigation)

PHPackages © 2026

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