Laravel Requent

An elegant, light-weight GQL (Graph Query Language) like interface for Eloquent with zero configuration. It maps a request to eloquent query and transforms the result based on query parameters. It also supports to transform the query result explicitly using user defined transformers which provides a more secured way to exchange data from a public API with minimal effort.

• Installation
• How It Works
• Basic Example
• Resource
• Methods
• Resource Key By
• Data Filtering Using Transformers
• Get Raw Result
• Query Modifier Clause
• Customizations

<a name="installation"></a> Installation

You can simply run the following command from your terminal to install the package:

composer require sheikhheera/requent

Or add the following line in "composer.json" file within "require" section and run composer install from terminal:

"sheikhheera/requent": "1.0.*"

If you are using version 5.5 or greater, then you are all done, no need to add service provider or alias in config\app. So you can simply skip the following steps because of Laravel's package auto discovery feature.

This will install the package. Now add the following entry in your config/app.php file inside the providers section:

Requent\RequentServiceProvider::class

Also add the following entry in aliases section of your config/app.php file:

'Requent' => Requent\Facade\Requent::class,

If you've done everything right then you can start using it without any configuration but you may customize it.

<a name="how-it-works"></a> How It Works

This package will allow us to query resources through the request query string parameter. For example, if we've a User model and the User model has many posts (Post model) and each post has many comments (Comment model) then we can query the users with their posts and comments of each posts by sending a request like the followig: http://example.com/users?fields=posts{comments}. This is the most basic use case but it offers more. We can also select properties of each model through query string, for example, if we want to select only the emal field from the User model and title from Post and body from the Comment model then we can just do it by sending a request using the following URL:

http://example.com/users?fields=email,posts.orderByDesc(id){title,comments{body}}

It'll be translated into something similar to following (Not literally):

User::select('email')
->with(['posts' => function($query) {
    $query
    ->orderByDesc('id')
    ->select('title')
    ->with(['comments' => function($query) {
        $query->select('body');
    }])
}]);

<a name="basic-example"></a> Basic Example

To use this package, we need to create some resources (Eloquent Models). For this demonstration, we'll use the same idea using User, Post and Comment models for an imaginary blog. The User model has a hasMany relation for posts and the Post model has a hasMany relation for comments. So, we need a route, which could be a resourceful route but we'll use an explicite route declaration here:

Route::get('users', 'UserController@index');

Now, we need a controller which is just a simple controller, for example:

<?php

namespace App\Http\Controllers;

use Requent;
use App\User;
use App\Http\Controllers\Controller;

class UserController extends Controller
{
    public function index()
    {
        return Requent::resource(User::class)->get();
    }
}

Now, we can make a request using: http://example.com/users?fields=email,posts{title,comments{body}}. This will give us the expected result, which would be an array of users (only email column from User) with all the related posts (only title column from Post) and all the comments of each post (only body column from Comment).

If we want to load any resource with relations without selecting any properties then we can just do it using the following request: http://example.com/users?fields=posts{comments}. This was the most basic example but let's explore it's features.

<a name="resource"></a> Resource

Actually, a resource is just an eloquent model, the first method we should call on the Requent class is resource which sets the primary resource we want to query on. So we can set the resource using couple of ways, for example:

$resource = Requent::resource(User::class);

Also, we can use an object, for example:

$resource = Requent::resource(new User);

We can also pass a Query Builder for example:

$resource = Requent::resource(app(User::class)->where('role', 'admin'));

So, we can call any scope methods as well, which just returns a Query Builder instance. The resource method returns the Requent object so we can chain methods, for example, we can call any query executing method (including other available methods in Requent), for example:

$result = Requent::resource(
    app(User::class)->where('role', 'admin')
)
->transformBy(UserTransformer::class)
->keyBy('users')
->get();

We'll walk-through all the available methods and features that Requent offers. Let's continue.

<a name="methods"></a> Methods

Get

We've seen get method earlier which just returns an array of users which is:

return Requent::resource(User::class)->get();

Paginated Result

At this point, we'll get an array but we can retrieve paginated result using same get method and in this case we, we only need to provide a query string parameter in our URL like the following example:

http://example.com/users?fields=posts{comments}&paginate

Also, we can set the paginator, for example:

http://example.com/users?fields=posts{comments}&paginate=simple

This will return the paginated result using SimplePaginator but by default it'll use LengthAwarePaginator.

Per Page

We can also tell how many pages we want to get for per page and it's just another parameter, for example:

http://example.com/users?fields=posts{comments}&paginate=simple&per_page=5

If we provide per_page=n then we don't need to provide &paginate parameter unless we want to use the simple paginator instead of default. We can also customize these parameters, we'll check later on.

Paginate

Also, we can call the paginate method on the Requent directly, for example:

return Requent::resource(User::class)->paginate(); // or paginate(10)

Simple Paginate

The simplePaginate will return paginated result using Simple Paginator. Check Laravel Documentation.

return Requent::resource(User::class)->simplePaginate(); // or simplePaginate(10)

Find

If we want to retrieve a single user then we can use find and first method, for example:

return Requent::resource(User::class)->find($id);

First

For the first item we can call the first method:

return Requent::resource(User::class)->first();

Fetch

These are all the available methods for executing query but there is one more method which is fetch. This method can return any kind of result, an collection (array), paginated result or a singlr resource. Let's see an example:

// In Controller

public function fetch($id = null)
{
    return Requent::resource(User::class)->fetch($id);
}

To use this method we need a route like: Route::get('users/{id?}', 'UserController@fetch') and then we can use this single route to get all kind of results, for example:

Get a collection of users (Array)

http://example.com/users?fields=posts{comments}

Get paginated result

http://example.com/users?fields=posts{comments}&paginate=simple&per_page=5

Get a single user (Array)

http://example.com/users/1?fields=posts{comments}

The fetch method will be useful if we declare explicit route other than RESTfull routes for Resource Controllers. Check Laravel Documentation.

When selecting properties of a model/resource using query string, i.e: fields=name,posts{title}, we can select a dynamic property (getter/accessor), defined using a getPropertyAttribute method. Check the documentation for Defining An Accessor.

<a name="key-by"></a> Resource Key By

The query results for a collection is simply an array with a zero based index but if we want then we can wrap our collection in a key using keyBy method, for example:

return Requent::resource(User::class)->keyBy('users')->get();

This will return a collection of users (Array) as a key value pair where the key will be users and the result will be the valuse of that key. We can also use a key for a single user for example:

return Requent::resource(User::class)->keyBy('user')->find(1);

In case of fetch we can use something like the following:

public function fetch($id = null)
{
    return Requent::resource(User::class)->keyBy($id ? 'user' : 'users')->fetch($id);
}

The paginated result will remain the same, by default Laravel wraps the collection using the data as key.

<a name="transformer"></a> Data Filtering Using Transformers

The idea of transformers is taken from Fractal Transformer package. This looks like re-inventin