jedrzej/pimpable

Laravel 4/5 package that allows to dynamically filter, sort and eager load relations for your models using request parameters

Pimp your API! Pimp your models!

Does your API need to allow filtering results? Of course it does!, _(*1)

Do you need to sort the results or return selected relations together with your model? I bet you do!, _(*2)

Let's do this!, _(*3)

Pimp your model!, _(*4)

class Post extends Eloquent {
    use PimpableTrait;
}

Pimp your API!, _(*5)

class PostsController extends Controller {
    public function index() {
        return Post::pimp()->get();
    }
}

What data do you need?, _(*6)

I need all the posts in a thread with ID 42..., _(*7)

...that contain a string "awesome"..., _(*8)

...that are no older than March 2014..., _(*9)

...that have been posted by any user other than the one with ID 666., _(*10)

One more thing... sort it so that I get active posts at the top..., _(*11)

Oh, and make active and inactive posts sorted by the date they were posted..., _(*12)

Did I mention I need the user data with every post?, _(*13)

Ready... Steady... Go!, _(*14)

GET /api/posts
  ?thread_id=42
  &text=%awesome%
  &created_at=(ge)201403
  &user_id=!666
  &sort[]=is_active,desc
  &sort[]=created_at,desc
  &with=user

BAM! Done! How cool is that!, _(*15)

Overview

Laravel 4/5/6 package that allows to dynamically filter, sort and eager load relations for your models using request parameters., _(*16)

It combines the following packages:, _(*17)

• Searchable - filter models
• Sortable - sort models
• Withable - eager load relations

It simplifies embedding them in your models and allows using all 3 of them with a single function call., _(*18)

Composer install

Add the following line to composer.json file in your project:, _(*19)

"jedrzej/pimpable": "0.0.6"

or run the following in the commandline in your project's root folder:, _(*20)

composer require "jedrzej/pimpable" "0.0.6"

Usage

Pimp your model

In order to pimp your model class, you need to import PimpableTrait into your model. This will internally import all 3 behaviours., _(*21)

class Model extends Eloquent {
    use PimpableTrait;
}

By default all model fields are searchable and sortable; all relations can be eagerly loaded by default as well. If you need to limit which fields can be filtered and sorted by and which relations can be loaded, see documentation of corresponding behaviour package., _(*22)

Pimp your API

Once you pimp your model, additional method pimp() will be available on the model that enables the additional behaviour. All criteria will be taken from the request automatically, but if you want to override the request parameters, you can pass the desired value to the pimp() method:, _(*23)

//override all parameters
return Model::pimp($filters, $sort, $relations)->get();

//override sorting criteria only
return Model::pimp(null, $sort)->get();

Information how to configure the behaviours using request parameters can be found in documentation of corresponding behaviour package., _(*24)

Additional configuration

If you are using sort request parameter for other purpose, you can change the name of the parameter that will be interpreted as sorting criteria by setting a $sortParameterName property in your model, e.g.:, _(*25)

protected $sortParameterName = 'sortBy';

If you are using with request parameter for other purpose, you can change the name of the parameter that will be interpreted as a list of relations to load by setting a $withParameterName property in your model, e.g.:, _(*26)

protected $withParameterName = 'relations';