Processor
A http query parameter processor is responsible for creating appropriate query filters, based on its assigned parameter value.
How it works
A query parameter is assigned to the processor. It is then responsible for validating the value of that parameter and create one or more query filters, which are stored inside a BuiltFiltersMap
component.
The processor is invoked by a builder, if a http query parameter is matched.
How to create processor
You can create a new processor by extending the BaseProcessor
abstraction.
use Aedart\Filters\BaseProcessor;
use Aedart\Contracts\Filters\BuiltFiltersMap;
use Acme\Models\Filters\SearchFilter;
class SimpleSearchProcessor extends BaseProcessor
{
public function process(BuiltFiltersMap $built, callable $next)
{
// E.g. skip if parameter was submitted with empty value...
$value = $this->value();
if (empty($value)) {
return $next($built);
}
// Create and assign your query filter
$filter = new SearchFilter($value);
$built->add($this->parameter(), $filter);
// Finally, process the next processor
return $next($built);
}
}
In the above shown example, a search filter instance is created and added to the "built filters map" - a data transfer object, which is passed through each processor. Laravel's pipeline is used behind the scene, for invoking the process()
method.
Validation
A received query parameter might contain incorrect or harmful value. You are therefore highly encouraged to validate the received input, before using it in a query filter. The following example shows a possible way to perform validation of a parameter's value.
use Aedart\Filters\Exceptions\InvalidParameter;
class SimpleSearchProcessor extends BaseProcessor
{
public function process(BuiltFiltersMap $built, callable $next)
{
// Fail if parameter's value is invalid...
$value = $this->value();
if (empty($value)) {
throw InvalidParameter::make($this, 'Empty value is not allowed');
}
// Create and assign your query filter
$filter = new SearchFilter($value);
$built->add($this->parameter(), $filter);
// Finally, process the next processor
return $next($built);
}
}
The builder that runs your processor will automatically handle any exceptions that inherit from InvalidParameterException
¹. Exceptions, of the mentioned kind, will be rethrown as Laravel's ValidationException
, which will result in a 422 Unprocessable Entity
http response in your typical Laravel Application.
¹: Aedart\Contracts\Filters\Exceptions\InvalidParameterException
Advanced Input Validation
You can also use Laravel's validator and let it do all the heavy lifting. The BaseProcessor
offers a reference to the validator factory, via the getValidatorFactory()
method.
class SimpleSearchProcessor extends BaseProcessor
{
public function process(BuiltFiltersMap $built, callable $next)
{
$validator = $this->getValidatorFactory()->make(
// The input...
[
'value' => $this->value()
],
// Validation rules...
[
'value' => 'required|string|min:3|max:150'
]
);
// Obtain valid input... or fail
$validated = $validator->validated();
// ... remaining not shown
}
}
Built Filters Map
The BuiltFiltersMap
DTO is intended be used as a temporary placeholder of all the filters that processors created.
Add filters
To add one or more filters, from your processor, use the add()
method. It accepts two arguments:
$key
:string
key name.filter
:Criteria
the query filter.
// ... inside your processor's process method ...
$built->add('my-parameter', new SearchFilter());
If a key already exists, then new filters are simply added to that key. This means that the same key can hold multiple query filters.
Obtain filters
To obtain filters, you can use the get()
method.
$filters = $built->get('my-parameter');
Obtain all filters
The all()
method will return a list of all added filters.
$filters = $built->all();
Arbitrary meta data
Sometimes, your processor might be required to store additional arbitrary data that other processors can use. If that is the case, then you can use setMeta()
and getMeta()
methods to do so.
// E.g. inside first processor...
$built->setMeta('use_admin_flag', true);
// E.g. inside another processor...
$useAdminFlag = $built->getMeta('use_admin_flag', false);
See Aedart\Contracts\Filters\BuiltFiltersMap
for additional reference of available methods.