, (*1)
ScopeApplicator brings an elegant way of sorting and filtering data to your PHP projects., (*2)
Overview
ScopeApplicator is an easy, logical and framework-agnostic way to achieve something like this:, (*3)
/posts – returns a list of all posts, (*4)
/posts?recent – returns only recent posts, (*5)
/posts?author_id=5 – returns posts belonging to an author with an id=5, (*6)
/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, (*7)
Requirements
— php >= 5.4, (*8)
Supported frameworks:
Installation
If you're using one of the supported frameworks, follow framework-specific installation instructions on its page., (*9)
Otherwise, you can install ScopeApplicator as follows:, (*10)
composer require mobileka/scope-applicator 1.1.*, (*11)
Usage
If you're using one of the supported frameworks, follow framework-specific usage instructions on its page., (*12)
Otherwise, you have to create a custom binding for your own framework or PHP-project., (*13)
TODO: add detailed instructions about bindings, (*14)
Configuration options
ScopeApplicator supports several configuration options and these are described in this chapter., (*15)
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., (*16)
Example:, (*17)
public $scopes = [
'orderByTitle' => ['alias' => 'order_by_title']
];
/posts?order_by_title – an orderByTitle scope will be applied, (*18)
/posts?orderByTitle – no scope will be applied, (*19)
Type
This option allows to cast a type of a parameter value before it will passed to a scope., (*20)
When type is set to bool or boolean, only 1 and true will be converted to true. Everything else is considered to be false., (*21)
If type is set to something different than bool or boolean, settype php function will be called., (*22)
Examples:, (*23)
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, (*24)
/posts?new=true – a new scope will be applied with boolean true as its argument, (*25)
/posts?new=yes – a new scope will be called with boolean false as its argument, (*26)
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., (*27)
Examples:, (*28)
public $scopes = [
'userId' => [
'alias' => 'author_id',
'default' => 5
]
];
/posts?author_id=1 - a userId scope will be applied with 1 as an argument, (*29)
/posts - a userId scope will be applied with 5 as an argument, (*30)
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., (*31)
Examples:, (*32)
public $scopes = [
'userId' => [
'alias' => 'author_id',
'allowEmpty' => true
]
];
/posts?author_id – a userId scope will be applied with '' (empty string) as an argument., (*33)
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., (*34)
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., (*35)
Keys (experimental)
Keys are used when a scope accepts multiple arguments., (*36)
Example:, (*37)
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, (*38)
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"., (*39)
Credits
Scope Applicator is inspired by has_scope Ruby gem., (*40)
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., (*41)
License
ScopeApplicator is an open-source software and licensed under the MIT License., (*42)
Wallogit.com
