plokko/querable-resource

Ajax-querable resource for Laravel 5.5

QuerableResource

A Laravel class that helps querying(paging and filtering) and returning Eloquent resources from Ajax., _(*1)

Supports Laravel 5.5 Resources., _(*2)

Installation

Install it throught composer composer require plokko/querable-resource, _(*3)

Quick start

First of all you need to extend the Plokko\QuerableResource\QuerableResource class implementing the getQuery method that returns the base query:, _(*4)

 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, _(*5)

Route::get('/test',function(){
    $qr = new TestQuerableResource();
    return $qr;
});

The page should return a basic resource with all the results, _(*6)

Pagination

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., _(*7)

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] ), _(*8)

Route::get('/test',function(){
    $qr = new TestQuerableResource();
    $qr->paginate(10); // Set pagination to 10 items per page
    return $qr;
});

Filtering results

To filter results extend the protected propriety $filteredFields specifying what fields you want to filter, _(*9)

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., _(*10)

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'., _(*11)

Alias

If you want to use a query parameter different from the field you can specify the alias as key for the field:, _(*12)

class TestQuerableResource extends \Plokko\QuerableResource\QuerableResource {
      protected
        $filteredFields = [
        'n' => 'name', // query parameter n to field name
        'mail' => 'email', // query parameter mail to field email
    ];
    //....
}

Advanced filtering options

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','>','>=',...), _(*13)

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
        ]
    ];
    //....
}

Changing query field name

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, _(*14)

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, _(*15)

Define filtering rules

Custom filtering function

If your query needs a more fine-tuning you can override the default filter function and specify your custom filtering function:, _(*16)

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!, _(*17)

Returning custom resource

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:, _(*18)

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., _(*19)

Javascript integration

This plugin contains some Javascript assets to help integrate with the php counterpart., _(*20)

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, _(*21)

// 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";