mobileka / scope-applicator by mobileka

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

• Overview
• Requirements
• Installation
• Supported frameworks
• Usage
• Configuration options
  • Alias
  • Type
  • Default
  • Allow Empty
  • Keys (experimental)
• Credits
• Contributing
• License

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

— php >= 5.4

Supported frameworks:

• Laravel ~5.1 (documentation)
• Laravel 5.0.x (documentation)
• Laravel 4.x.x (documentation)
• Laravel 3.x.x (documentation)
• Yii 2.0.x (documentation)

Installation

If you're using one of the 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

If you're using one of the 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

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

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

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

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

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

Scope Applicator is inspired by has_scope Ruby gem.

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

ScopeApplicator is an open-source software and licensed under the MIT License.