optimus/bruno

Bruno

, _(*1)

Introduction

A Laravel base controller class and a trait that will enable to add filtering, sorting, eager loading and pagination to your resource URLs., _(*2)

Dedicated to Giordano Bruno, _(*3)

This package is named after my hero Giordano Bruno. A true visionary who dared to dream beyond what was thought possible. For his ideas and his refusal to renounce them he was burned to the stake in 1600. I highly recommend this short cartoon on his life narrated by Neil deGrasse Tyson., _(*4)

Functionality

• Parse GET parameters for dynamic eager loading of related resources, sorting and pagination
• Advanced filtering of resources using filter groups
• Use Optimus\Architect for sideloading, id loading or embedded loading of related resources
• ... Ideas for new functionality is welcome here

Tutorial

To get started with Bruno I highly recommend my article on resource controls in Laravel APIs, _(*5)

Installation

For Laravel 5.3 and below, _(*6)

composer require optimus/bruno ~2.0

For Laravel 5.4 and above, _(*7)

composer require optimus/bruno ~3.0

Usage

The examples will be of a hypothetical resource endpoint /books which will return a collection of Book, each belonging to a Author., _(*8)

Book n ----- 1 Author

Available query parameters

Implementation

<?php

namespace App\Http\Controllers;

use Optimus\Api\Controller\EloquentBuilderTrait;
use Optimus\Api\Controller\LaravelController;
use App\Models\Book;

class BookController extends LaravelController
{
    use EloquentBuilderTrait;

    public function getBooks()
    {
        // Parse the resource options given by GET parameters
        $resourceOptions = $this->parseResourceOptions();

        // Start a new query for books using Eloquent query builder
        // (This would normally live somewhere else, e.g. in a Repository)
        $query = Book::query();
        $this->applyResourceOptions($query, $resourceOptions);
        $books = $query->get();

        // Parse the data using Optimus\Architect
        $parsedData = $this->parseData($books, $resourceOptions, 'books');

        // Create JSON response of parsed data
        return $this->response($parsedData);
    }
}

Syntax documentation

Eager loading

Simple eager load, _(*9)

/books?includes[]=author, _(*10)

Will return a collection of 5 Books eager loaded with Author., _(*11)

IDs mode, _(*12)

/books?includes[]=author:ids, _(*13)

Will return a collection of Books eager loaded with the ID of their Author, _(*14)

Sideload mode, _(*15)

/books?includes[]=author:sideload, _(*16)

Will return a collection of Books and a eager loaded collection of their Authors in the root scope., _(*17)

See mere about eager loading types in Optimus\Architect's README, _(*18)

Pagination

Two parameters are available: limit and page. limit will determine the number of records per page and page will determine the current page., _(*19)

/books?limit=10&page=3, _(*20)

Will return books number 30-40., _(*21)

Sorting

Should be defined as an array of sorting rules. They will be applied in the order of which they are defined., _(*22)

Sorting rules, _(*23)

Example, _(*24)

[
    {
        "key": "title",
        "direction": "ASC"
    }, {
        "key": "year",
        "direction": "DESC"
    }
]

Will result in the books being sorted by title in ascending order and then year in descending order., _(*25)

Filtering

Should be defined as an array of filter groups., _(*26)

Filter groups, _(*27)

Filters, _(*28)

Operators, _(*29)

Special values, _(*30)

Custom filters

Remember our relationship Books n ----- 1 Author. Imagine your want to filter books by Author name., _(*31)

[
    {
        "filters": [
            {
                "key": "author",
                "value": "Optimus",
                "operator": "sw"
            }
        ]
    }
]

Now that is all good, however there is no author property on our model since it is a relationship. This would cause an error since Eloquent would try to use a where clause on the non-existant author property. We can fix this by implementing a custom filter. Where ever you are using the EloquentBuilderTrait implement a function named filterAuthor, _(*32)

public function filterAuthor(Builder $query, $method, $clauseOperator, $value)
{
    // if clauseOperator is idential to false,
    //     we are using a specific SQL method in its place (e.g. `in`, `between`)
    if ($clauseOperator === false) {
        call_user_func([$query, $method], 'authors.name', $value);
    } else {
        call_user_func([$query, $method], 'authors.name', $clauseOperator, $value);
    }
}

Note: It is important to note that a custom filter will look for a relationship with the same name of the property. E.g. if trying to use a custom filter for a property named author then Bruno will try to eagerload the author relationship from the Book model., _(*33)

Custom filter function, _(*34)

Examples

[
    {
        "or": true,
        "filters": [
            {
                "key": "author",
                "value": "Optimus",
                "operator": "sw"
            },
            {
                "key": "author",
                "value": "Prime",
                "operator": "ew"
            }
        ]
    }
]

Books with authors whoose name start with Optimus or ends with Prime., _(*35)

[
    {
        "filters": [
            {
                "key": "author",
                "value": "Brian",
                "operator": "sw"
            }
        ]
    },
    {
        "filters": [
            {
                "key": "year",
                "value": 1990,
                "operator": "gt"
            },
            {
                "key": "year",
                "value": 2000,
                "operator": "lt"
            }
        ]
    }
]

Books with authors whoose name start with Brian and which were published between years 1990 and 2000., _(*36)

Optional Shorthand Filtering Syntax (Shorthand)

Filters may be optionally expressed in Shorthand, which takes the a given filter array[key, operator, value, not(optional)] and builds a verbose filter array upon evaluation., _(*37)

For example, this group of filters (Verbose), _(*38)

[
    {
        "or": false,
        "filters": [
            {
                "key": "author",
                "value": "Optimus",
                "operator": "sw"
            },
            {
                "key": "author",
                "value": "Prime",
                "operator": "ew"
            }
            {
                "key": "deleted_at",
                "value": null,
                "operator": "eq",
                "not": true
            }
        ]
    }
]

May be expressed in this manner (Shorthand), _(*39)

[
    {
        "or": false,
        "filters": [
            ["author", "sw", "Optimus"],
            ["author", "ew", "Prime"],
            ["deleted_at", "eq", null, true]
        ]
    }
]

Standards

This package is compliant with PSR-1, PSR-2 and PSR-4. If you notice compliance oversights, please send a patch via pull request., _(*40)

Testing

bash $ phpunit, _(*41)

Contributing

Please see CONTRIBUTING for details., _(*42)

License

The MIT License (MIT). Please see License File for more information., _(*43)