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 3w 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 72% 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

3725d 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

[millat/laravel-hooks

The WordPress filter, action system in Laravel

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

Data sanitizer for PHP with built-in Laravel support.

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

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

285.3k](/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)

PHPackages © 2026

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