A Laravel class that helps querying(paging and filtering) and returning Eloquent resources from Ajax.
Supports Laravel 5.5 Resources.
Install it throught composer composer require plokko/querable-resource
First of all you need to extend the Plokko\QuerableResource\QuerableResource
class implementing the getQuery method that returns the base query:
class TestQuerableResource extends \Plokko\QuerableResource\QuerableResource {
protected function getQuery(): Illuminate\Database\Eloquent\Builder
{
return App\User::where('id','>',1); // Just a simple query to demonstrate functionality
}
}
Next we're going to instantiate it and return it to the request
Route::get('/test',function(){
$qr = new TestQuerableResource();
return $qr;
});
The page should return a basic resource with all the results
To enable pagination edit the $paginate protected propriety or via the pagination() method setting it to the wanted page size or to null to disable it.
class TestQuerableResource extends \Plokko\QuerableResource\QuerableResource {
protected
$paginate = 30,//30 items per page
/**
* Allowed client-defined paginations,
* if null no client pagination is allowed
* if int set the maxium page size allowed
* if array only the page sizes listed in the array are allowed
* @var int|array|null
*/
$paginations = 100;
protected function getQuery(): Illuminate\Database\Eloquent\Builder
{
return App\User::where('id','>',1); // Just a simple query to demonstrate functionality
}
}
The propriety $paginations specify the user-selectable available values, if the value is null
only $paginate user values will be discarted in favor of $paginate, if an int value is specified it will be set as the maxium value (in this case the user could select pagination up to 100 with default of 30 items per page); if an array (of integers) is specified the user value must be contained in the array or $paginate value will be used (ex. [10,20,30,50]
)
Route::get('/test',function(){
$qr = new TestQuerableResource();
$qr->paginate(10); // Set pagination to 10 items per page
return $qr;
});
To filter results extend the protected propriety $filteredFields specifying what fields you want to filter
class TestQuerableResource extends \Plokko\QuerableResource\QuerableResource {
protected
$filteredFields = ['name','email']; // enable filtering for name and email columns
protected function getQuery(): Illuminate\Database\Eloquent\Builder
{
return App\User::where('id','>',1); // Just a simple query to demonstrate functionality
}
}
You do not need to pass anything to the resource, the filtering is automatic and transparent.
Route::get('/test',function(){
$qr = new TestQuerableResource();
return $qr;
});
By default the comparison is done with the LIKE 'value%'; for example the page /test?name=a
will search all the user with a name starting with 'a'.
If you want to use a query parameter different from the field you can specify the alias as key for the field:
class TestQuerableResource extends \Plokko\QuerableResource\QuerableResource {
protected
$filteredFields = [
'n' => 'name', // query parameter n to field name
'mail' => 'email', // query parameter mail to field email
];
//....
}
Instead of the field name you can specify an array of filtering options like
- field - string (required) - corresponding field name, required
- type - string - type of comparaison (ex. '=','like','>','>=',...)
class TestQuerableResource extends \Plokko\QuerableResource\QuerableResource {
protected
$filteredFields = [
'n' => [ //an can be used
'field'=>'name',
'type'=>'like',
],
[
'field'=>'email', // If no alias is specified field will be used as query parameter
//comparaison type is optional
]
];
//....
}
If you want to group all filtering field in an input group, for example filter[filed_name], you need to edit the protected propriety $filterQueryParameter
class TestQuerableResource extends \Plokko\QuerableResource\QuerableResource {
protected
$filteredFields = ['name','email'], // enable filtering for name and email columns
$filterQueryParameter='filter';
protected function getQuery(): Illuminate\Database\Eloquent\Builder
{
return App\User::where('id','>',1); // Just a simple query to demonstrate functionality
}
}
The url of the last example will now be /test?filter[name]=a
If your query needs a more fine-tuning you can override the default filter function and specify your custom filtering function:
class TestQuerableResource extends \Plokko\QuerableResource\QuerableResource {
// No need to specify $filteredFields, we're using a custom filtering function
//Override the default filtering function
protected function filter(Builder &$query,array $filterValues){
if(array_key_exists('name',$filterValues)){
$query->where('name','LIKE','%'.$filterValues['name'].'%');//apply your filtering
}
//....
}
protected function getQuery(): Illuminate\Database\Eloquent\Builder
{
return App\User::where('id','>',1); // Just a simple query to demonstrate functionality
}
}
Don't worry, pagination and query field name will also be automatically applied to your filtering, no need to implement them!
If you want to filter the results with a custom resource you can do it by simply specifying the name of your Resource class in the protected field $useResource:
class TestQuerableResource extends \Plokko\QuerableResource\QuerableResource {
protected
$useResource = \App\Http\Resources\UserResource::class;
protected function getQuery(): Illuminate\Database\Eloquent\Builder
{
return App\User::where('id','>',1); // Just a simple query to demonstrate functionality
}
}
The class will now return the specified resource (as a collection); for further detail on resources see Laravel 5.5 API resources doc.
This plugin contains some Javascript assets to help integrate with the php counterpart.
This plugin includes two main helper:
- ResourceQuery For building an Ajax request to the php plugin counterpart
- QuerableResult Wrapper of ResourceQuery that returns a querable result instead of a query, usefull especially in Vue.js applications
// Import from the /vendor folder, this path is related to /resources/assets/js/components/
// Import QuerableResult and ResourceQuery (optional)
import QuerableResult,{ResourceQuery} from "../../../../vendor/plokko/querable-resource/assets/js/QuerableResult";
// Or just ResourceQuery
//import ResourceQuery from "../../../../vendor/plokko/querable-resource/assets/js/ResourceQuery";