Download the PHP package aros/omnifetch-lumen without Composer

OmniFetch for Lumen

OmniFetch for Lumen is a useful library which makes fetch API endpoints easier to set up and flexible enough for different situations. The library allows for easy modification of the response data set on the fly by passing in query parameters as part of the request. These modifications can range from apply filters, embedding related data and pagination to aggregating data with group bys.

Installation

Dependencies

• Lumen >= 5.5

Main Functionalities

OmniFetch has only two methods that can be used. They are the following:

• OmniFetch::getSingle(Illuminate\Database\Eloquent\Builder $builder, array $params) - used to fetch a single record.
• OmniFetch::paginate(Illuminate\Database\Eloquent\Builder $builder, array $params) - used to fetch a list of records

The builder being used should be created using a model (i.e. primary model). e.g. Author::query()

Parameter Options

The OmniFetch::getSingle and OmniFetch::paginate both require the $params in their arguments which is an associative array of options.

• filters (data type: JSON list /array): Adds criteria to the query. It can take as many criteria as required. Each criterion is a JSON object (if filters is a JSON list, this format is best if it is passed as a request query parameter) or an associative array (if filters is an array). It contains the following fields:

  • field (required): the field used for the filtering. It can be a field from the primary model or a related model (which can be done by indicating the relation name specified in the primary model followed by the relation's field. e.g. author.rating ). It supports nested relations fields e.g. author.publisher.is_local.
  • value (required): the value to be used.

  Note: if % is used in the value it needs to be URL encoded if it is passed as a request query parameter.

  • cond_op (optional | default: '='): the conditional operator used in comparing the field and value. The available operators are: =, !=, >, <, >=, <=, LIKE, IS_NULL (only field is needed), IS_NOT_NULL (only field is needed).
  • logical_op (optional | default: 'AND'): the logical operator used to combine the remaining filters after it. The available operators are AND and OR.

  Examples:

  • [{"field": "status_id", "value": 1}] => ... WHERE primary_table.status_id = 1;
  • [{"field": "name", "value": "%25rich%25", "cond_op": "LIKE"}] => ... WHERE primary_table.name LIKE "%rich%";
  • [{"field": "status_id", "value": 1}, {"field": "author.rating": "value": 2.5, "cond_op": ">="}] => ... WHERE primary_table.status_id = 1 AND author.rating >= 2.5
  • [{"field": "likes", "value": 100, "cond_op": ">", "logical_op": "OR"}, {"field": "rating", "value": 4.0, "cond_op": ">="}, {"field": "rating", "value": 4.5, "cond_op": "<="}] => ... WHERE primary_table.like > 100 OR (primary_table.rating >= 4.0 AND primary_table.rating <= 4.5)

• embeds (data type: JSON list /array): Embeds related model data to the primary model being fetched. Only names of relations of the primary model and their relations are allowed (this means that nested relations allowed).

  Examples :

  • ["status", "author.publisher"]

• no_pages (data type: boolean | default is false): Specifies whether not or to paginate.

• page (data type: integer | default: 1): Specifies the current page when paginating

• page_size (data type: integer | default: 20): Specifies the number of records returned for a page when paginating

• order_by (data type: string): Specifies the field to order by (relation field are not supported for now).

• is_asc (data type: boolean | default: true): Specifies the ordering direction

• aggs (data type: JSON list /array): Used for performing aggregations such as sum, min and max. Each aggregation specified in the list is a JSON object (if aggs is a JSON list) or associative array (if aggs is an array). The following are the fields that each aggregation can have:

  • field (required): The field to be aggregated. This can be a field of a relation. Nested relations are allowed.

    Note: In order to use relation fields, the primary model must have the OmniFetch\HasJoinWith trait.

  • alias (required): The alias used for the aggregation.
  • func (required): The aggregation function. The following are available:
    • count => COUNT({{col}})
    • avg => AVG({{col}})
    • min => MIN({{col}})
    • max => MAX({{col}})
    • sum => SUM({{col}})

  Examples:

  • [{"field": "likes", "func": "sum", "alias": "total_likes"}] => SELECT SUM(primary_table.likes) AS total_likes ...

• group_by (data type: JSON list /array): Used for grouping data. Each group-by column is represented with a JSON object (if group_by is a JSON list) or associative array (if group_by is an array). The following are the fields that can be used for each group-by:

  • field (required): The field to be used for the group-by. This can be a field of a relation. Nested relations are allowed.

    Note: To use relation fields, the primary model must have the OmniFetch\HasJoinWith trait.

  • func (optional): The group-by function. The following are available:
    • date => DATE({{col}})
    • month => DATE_FORMAT({{col}}, '%Y-%m')
    • year => YEAR({{col}})
  • alias (required if func is used): The alias used for the group by.

  Examples:

  • [{"field": "created_at", "func": "date", "alias": "created_date"}] => ... GROUP BY DATE(primary_table.created_at) AS created_date

Usage

This can be explained with an example. In this example, getOnePost and getAllPosts endpoints are created. The models (or entities) used are:

• Publisher: a company which hires authors to write posts.
• Author: a person that writes posts and belongs to a publisher.
• Post: a piece of content written by authors.

For this example, Post is the primary model while Author and Publisher are related models.

Note: For the library to be very effective, the model relations should be well set up

First, lets set up the models (assuming DB migrations and other project prerequisites have been done):

Publisher Model

Author Model

Post Model

Secondly, lets set up the Controller

Finally, add the routes (and we are done!)

Request Examples with Response

• GET {{base_url}}/posts/1?embeds=["author"]

  Response

  Click to show response

• GET {{base_url}}/posts?page=3&page_size=2&filters=[{"field": "author.rating", "value": 3.5, "cond_op": ">"}]&embeds=["author.publisher"]&order_by=likes&is_asc=0

  Response

  Click to show response

• GET {{base_url}}/posts?aggs=[{"field": "author.rating", "func": "avg", "alias": "average_rating"}]&group_by=[{"field": "author.publisher.name", "alias": "publisher_name"}]&page_size=3

  Note: When using aggs or group_by it limits the fields returned to the aggs and group_by fields

  Response

  Click to show response