Download the PHP package sheikhheera/requent without Composer

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

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.

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):

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:

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

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.

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:

Also, we can use an object, for example:

We can also pass a Query Builder for example:

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:

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

Methods

Get

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

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:

Simple Paginate

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

Find

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

First

For the first item we can call the first method:

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:

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)

Get paginated result

Get a single user (Array)

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.

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:

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:

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

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

Data Filtering Using Transformers

The idea of transformers is taken from Fractal Transformer package. This looks like re-inventing the wheel but actually it's not. The main intention for building the Requent package was to allow an easy to use interface for fetching resource/data form a web application (non-public API), which allows to read data from server using any javaScript framework/library even without defining any transformers. Also, the Eloquent query is built dynamically on the run-time to load everything eagerly, while Fractal uses lazy loading. So, the Requent couldn't utilize the data transforming feature that Fractal offers. So, to provide the data filtering layer (for public API), the Requent needed it's own data filtering mechanism but the Fractal package is great and I've used it exclusively on my projects.

So far we've seen the default data transformation, which means that, a user can get any property or available relations of the resource just by asking it through the query string parameter fields (we can use something else other than fields), but there is no way to keep some data private if you are using this for a public API. Here, the transformer comes into play.

By default, the Requent uses a DefaultTransformer class to return only selected properties/relations, for example, if you send a request using a URL like following: http://example.com/users?fields=email,posts{title,comments} then it'll return only selected properties/relations. In this case, it'll return what you ask for it but you may need to define explicitly what properties/relations a user can get from a request through query parameter. For this, you can create a custom transformer where you can tell what to return. To create a trunsformer, you just need to create transformer classes by extending the Requent\Transformer\Transformer class. For example:

To use your custom transformer, all you need to pass the transformer class to the resource method, i.e:

Also you can pass the class instance:

Also, you can set the transformer using transformBy method:

Also, the transformBy method accepts a transformer object instance:

This will transform the resource using by calling the transform method defined in the transformer class you created. In this case, the transform mathod will called to transform the User model but right now, it'll not load any relations. Which means, if the URL is something like: http://example.com/users?fields=posts{comments} then only the User model will be transformed and the result would be something like the following:

To load any relations from the root transformer (UserTransformer in this case), we also need to explicitly declare a method using the same name the relation is defined in the model, so for example to load the related posts with each User model we need to declare a posts method in our UserTransformer class. For example:

In this example, we've added a filtering for Post model and that's why a user can select the related posts with users from the URL, for example: http://example.com/users?fields=posts. without the posts method in UserTransformer a user can't read/fetch the posts relation. At this point, we are not done yet. As you can assume that, we are transforming the posts (Collection) using items method available in UserTransformer (extended from abstract Transform class) and passing another transformer (PostTransformer) to transform the collection of posts. So, we need to implement the PostTransformer and have to implement the transform method where we'll explicitly return the transformed array for each Post model, for example:

In this example, we've implemented the transform method for the Post model for response filtering so only the id, title and body column will be available for the Post model in the response and the related posts will be included only if the user selects the posts through the query string parameter in the URL.

In the exmple given above, we've also defined two additional methods, user and comments. Those methods are also relations of Post model. The user method is defined as a belongsTo relationship which simply maps the related user who published the post and the comments method loads the related comments published under the post. The Post model looks something like the followin:

According to the setup given above, we can make a request using the following URL to get all the users with posts and it's related comments and user: http://example.com/users?fields=posts{user,comments}.

In the PostTransformer class we've used item method inside user method, which actually resieves a single Eloquent model in $model parameter and so we've called the item method from the transformer. In the comments method, we've used the items method because the $collection parameter in comments method recieves a collection of Comment models.

So, it's obvious that, to allow the inclussion of any relation from a resource we've to declare a method for that relation using the same name we've used to declare the relation in the Eloquent model and relations will be included only if the user selects/includes it within the fields parameter. If user selects a relation from a resource that is not exposed throught the transformer using a method, then it'll not be available in the response.

The user defined transformers will be used to transform the data only a transformer class is passed as the second parameter in the resource method or by calling the transformBy method, otherwise, everything will be included in the result/response the user asked for (if those fields/relations are available in the corresponding model).

Get Raw Result

Requent has a raw method which could be useful if someone doesn't want to apply any transformation, because after the transformation, the returned data is an array. So if you want to execute the query but you want to ommit the data transformation by default (selection of columns through the query string) then you can use raw method, for example:

In this case, when you don't provide a custom transformer to transform data then the requent will transform the data using the defalt transformer. So, if you make a request using http://example.com/users?fields=email,posts{title}, then it should return only email from the User model and title from the Post model.

In this case, because of raw, the requent will execute the query to load the resource with mentioned relations but it'll not filter the result so the original result returned by the Eloquent (could be a collection, paginated data or a modeld) will be returned as the result of Requent query.

Transform Raw Result

In this example, the third parameter users passed to transform method is optional, which would be used as the resource key.

The Requent doesn't use lazy loading, which means that, everything (relations) is eager loaded and when it comes to transformer (transform method), the quwey has been already executed and everything is loaded. So, at this point, the transform method will recieve a model and and if we want to load other relations that was not loaded through the query, then we can simply call the load method on the model before transforming it, for example:

Query Modifier Clause

When we make a request, we can add some query modifier clauses for example, orderBy, orderByDesc e.t.c. There are several clauses that Requent offers to use in the URL, those are given below:

orderBy

orderByDesc

skip & take

offset & limit

Multiple Clauses

When using limit/take on a relationship and loading a collection of that relation, you may get wrong result because the limit is applied only once on the query by Laravel. An old issue here.

Customizations

Requent uses some base settings from a config file. By default, it'll work as it's configured but if you need to modify any of the settings then you can publish the config file from vendor to your local app config directory. To publish the config, just execute the following command from your terminal:

Once you publish the config file to your local /config directory then you can modify any settings to customize Requent for your need. Follwing code is taken from the config file which is documented itself.