Home

Resource-query

Automatic filtering and sorting for Laravel queries with Ajax capabilities.

In most of Laravel applications there is a need to show data to the user with filtering and ordering capabilities. Usually this is a tedious process and no libraries except for pagination and data representation (JsonResource) are provided.

This library offers a way to easly define filtering and ordering capabilities for the user (Ajax), pagination and resource casting in a well readable and reusable class.

Installation

Install it via composer composer require plokko\resource-query

Definition

To initialize ResourceQuery you need to specify the base query; this query will be used in all request and filter and ordering functions will be added to it.

NOTE: The user query may only add filters and will not remove any conditions set on the base query so if you need to apply restriction you should apply them on the base query as they are not editable by the user; this applies also to sorting so you should avoid applying ordering in the base query if you want to enable user sorting as the user preferences will be added after the ordering on the base query.

There are two ways of using ResourceQuery: by extending the ResourceQuery class or in-place by using the QueryHelper class. The first approach is more usefull if you plan to use the same query in different places, the second method is more flexible if you plan to use it one time only and you want to avoid the definition of a new class just for that.

Extending ResourceQuery

Create a new class that extends plokko\ResourceQuery\ResourceQuery and implement the function getQuery() that will return the base query

use App\Models\User;
use plokko\ResourceQuery\ResourceQuery;

class ExampleResourceQuery extends ResourceQuery{

    protected function getQuery():Builder {
        // Return the base query
        return User::select(['id','name','email'])->where('id','>',0); // Just a simple query to demonstrate functionality
    }
    
}

Using the builder

use plokko\ResourceQuery\ResourceQueryBuilder;
//...
$query = User::select(['id','name','email'])->where('id','>',0);
//Add the base query
$resource =  new ResourceQueryBuilder($query);

See Filters, Sorting, Pagination or Resource casting sections for further informations.

Use

The ResourceQuery class can be either be used as an Eloquent collection, returned as a response or cast as a JSON string or Array (with the toArray function); the class will automatically resolve the query, apply filter and cast itself to the proper value.

This can be especially usefull if you plan to render the page via Php accessing the ResourceQuery instance as a collection but update all subsequent request with Ajax functions.

class MyController extends Controller {
    //...
    public function example1(Request $request){
        $resource = new ExampleResourceQuery();
        if($request->ajax()){
            return $resource;//Return data to the Ajax request
        }
        view('example',compact('resource'));
    }

    /**
    * Using the builder
    */
    public function example2(Request $request){
        $query = User::select(['id','name','email'])->where('id','>',0);
        $resource =  new ResourceQueryBuilder($query);

        if($request->ajax()){
            return $resource;
        }
        view('example',compact('resource'));
    }
    //...
}

Fluent definition

This class uses fluent definition that enables setting definition in an elegant and readable way automatically changing scope based on what is requested:

$qr->filter('filter1)//enters filter1 filter scope
      ->field('field1')
      ->condition('like')
   ->filter('filter2)//enters filter2 filter scope
      ->field('field2')
      ->condition('like%')
   ->orderBy('order1')//enters order1 order scope
      //...
   ->removeFilter('example')
//...
;