osmose
osmose copied to clipboard
Elegant filtering for laravel's eloquent models
Osmose Eloquent Filter
An elegant way to filter your eloquent collections
Getting Started
To pull osmose in your project, use the command
composer require agog/osmose
Defining Osmose Filters
Osmose provides an artisan command make-filter
that accepts the name of the filter to be generated, which quickly scaffolds a filter class
php artisan osmose:make-filter CharacterFilter
A CharacterFilter.php
file will be created in the App\Http\Filters
namespace.
NB: The Filters folder will be automatically created if it does not exist.
A filter class extends the Agog\Osmose\Library\OsmoseFilter
template and implements the Agog\Osmose\Library\Services\Contracts\OsmoseFilterInterface
interface.
It must define a residue
method that returns an array defining the filtration rules
<?php
namespace App\Http\Filters;
use Agog\Osmose\Library\OsmoseFilter;
use Agog\Osmose\Library\Services\Contracts\OsmoseFilterInterface;
class CharacterFilter extends OsmoseFilter implements OsmoseFilterInterface
{
/**
* defines the form elements that are to be sieved
* @return array
*/
public function residue() : array
{
return [
//
];
}
}
Usage
In order to use the osmose filter, you define rules as an array within the residue method's
Rules are defined as key => value pairs with the key representing the parameter passed as the request and the value represents the rule construct.
Rules are defined based on the type of filter driver intended. Osmose presents three internal filter drivers
1. Agog\Osmose\Library\Drivers\DirectFilter
2. Agog\Osmose\Library\Drivers\CallbackFilter
3. Agog\Osmose\Library\Drivers\RelationshipFilter
In our business logic, we call Osmose's sieve method on the filter object and pass the eloquent class that we intend to filter The sieve method will return Eloquent's builder.
CharacterController.php
public function index (CharacterFilter $filter)
{
$characters = $filter->sieve(Character::class)->get();
}
Consider the following tables and their related eloquent models
Character.php
id | name | gender |
---|---|---|
1 | Baraka | male |
2 | Cassie Cage | female |
3 | D'Vorah | female |
4 | Geras | male |
5 | Cetrion | female |
Role.php
id | name |
---|---|
1 | hero |
2 | villain |
3 | god |
CharacterRole.php
id | character_id | role_id |
---|---|---|
1 | 1 | 2 |
2 | 2 | 1 |
3 | 3 | 2 |
4 | 4 | 2 |
5 | 4 | 3 |
6 | 5 | 3 |
DirectFilter
To use the DirectFilter driver, we define the rule, prefixed with the word 'column'
public function residue () : array
{
return [
'character_id' => 'column:id'
]
}
Osmose will then look for the key 'character_id' within the request object and only return the result whose id matches the value passed
/characters?character_id=1
Will return the character record with an id of '1'
RelationshipFilter
To use the RelationshipFilter driver, we define the rule, prefixed with the word 'relationship', giving the name of the relationship and the column that should be checked in the related table
public function residue () : array
{
return [
'role' => 'relationship:roles,name'
]
}
NB: It is assumed a roles (belongsToMany) relationship exists in the Character model.
Osmose will then look for the key 'role' within the request object and only return the result based on the rule definition
/characters?role=god
Will return all characters with the role of 'god'
CallbackFilter
To use the CallbackFilter driver, we pass a callback that takes in the query builder and the value of the request as arguments. The callback must return the result of the builder
public function residue () : array
{
return [
'gender' => function ($query, $value) {
return $query->where('gender', $value);
}
]
}
Osmose will then look for the key 'gender' within the request object and only return results based on the callback
/characters?gender=male
Will return all male characters
Filtering Dates
As of version 2.0.0, osmose has introduced three new methods to assist in date filtering. These methods are;
public function column () : string
{
return 'created_at';
}
public function range ()
{
return 'range';
}
public function limits () : array
{
return [
'from' => 'from',
'to' => 'to'
];
}
The column() method
The column()
method returns a string indicating the column to be filtered once the sieve method on the filter class is executed. It defaults to the created_at
column. Simply override the method in your filter class, returning your desired column.
The range() method
To use this feature, you must publish osmose's configuration file by running;
This method replaces the range
property that was available in previous versions. It has a similar API, in which it returns the query parameter to be examined against, given predefined ranges within osmose's configuration file. Override the method to return an appropriate range string.
If the defined range does not exist within the GET
parameters, then osmose will not execute the range functionality.
The limits() method
The limits method refines date filtering within osmose by allowing one to configure request options. This methods returns an array with two keys from
and to
which indicate the request parameters.
The bound() method
Version 2.0.0 of osmose introduces the bound()
method. This method, like the residue method returns an array of rule definitions. Rules defined in this method are ALWAYS executed and do not rely on a query parameter being passed in the url. As such, these rules are not defined as key => value pairs but simply as values in the array.
NB: Only the direct and callback filters are currently supported.
Values in the bound()
method must be explicitly passed when defining the rules. Therefore, the CallbackFilter driver takes only one argument i.e the query builder.
public function bound () : array
{
return [
'column:id,1,2,3,4', // will always return records with the IDs defined whenever the route is visited,
function ($query) {
return $query->orWhere('id', 5); // adds record where id=5
}
];
}
You can automatically create the bound method by passing the bound option when creating an osmose filter.
php artisan osmose:make-filter ExampleFilter --bound
or php artisan osmose:make-filter ExampleFilter -b
The Global Osmose Function
Version 1.2.0 introduces a global function, osmose()
, that can automatically detect a model class from the filter.
To use this feature, you must publish osmose's configuration file by running;
php artisan vendor:publish --provider="Agog\Osmose\Providers\OsmoseServiceProvider"
To automatically detect models, the convention ${ModelName}Filter
should be followed when creating filters
For example, a filter named CharacterFilter will look for and automatically load a model called Character.
By default, osmose looks for models within the App namespace but this can be configured by changing the namespace's keyfrom within osmose's configuration file.
The osmose()
function receives the filter's fully qualified class name and an optional model name.
It returns Eloquent's builder just like the sieve() method.
public function index ()
{
$characters = osmose(CharacterFilter::class)->get();
}
if the model name completely differs from the filter or if there isn't a single namespace under which models reside. e.g in a micro service architecture, then you can pass the model's fully qualified name as a second argument to the osmose function.
public function index ()
{
$characters = osmose(UserSieve::class, Character::class)->get();
}
Feature Requests
If you have any feature requests, security vulnerabilities or just a good ol' thumbs up, dont hesitate to drop an email at [email protected]
Inspiration
This project was inspired by laravel's request validation. The name osmose comes from the biological word osmosis and how particles are able to filter through semi-permeable membranes. :)