README

OpenCubes

OpenCubes is a framework-agnostic set of components that parses PSR-7 URIs into value objects:

Pagination
Filters
Sorting
Breakdown (group by)

Overview

Look at the following URL:

https://your.application/books?page=3&per_page=50&sort[author.name]=asc&filters[published_at]=[2019-01-01+TO+2019-01-31]&filters[category_id]=12&filters[tags][]=foo&filters[tags][]=bar&filters[name][NOT][STARTS_WITH]=foo

Here's how OpenCubes parses it:

use BenTools\OpenCubes\Component\Filter\FilterComponent;
use BenTools\OpenCubes\Component\Sort\SortComponent;
use BenTools\OpenCubes\Component\Pager\PagerComponent;
use BenTools\OpenCubes\Component\Filter\Model\CollectionFilter;
use BenTools\OpenCubes\Component\Filter\Model\RangeFilter;
use BenTools\OpenCubes\Component\Filter\Model\SimpleFilter;
use BenTools\OpenCubes\Component\Filter\Model\StringMatchFilter;
use BenTools\OpenCubes\OpenCubes;
use function BenTools\OpenCubes\current_location;

$openCubes = OpenCubes::create();
$sorting = $openCubes->getComponent(SortComponent::getName());
$filters = $openCubes->getComponent(FilterComponent::getName());
$pager = $openCubes->getComponent(
    PagerComponent::getName(),
    ['default_size' => 100],
    current_location() // current_location() is the default and can be replaced by any PSR-7 Uri object
);

// Pagination
echo $pager->getCurrentPage(); // 3
echo $pager->getPerPage(); // 50 (it would be 100 when omiting the per_page parameter)
echo $pager->getCurrentOffset(); // 100

$pager->setNbItems(160); // Your application found 160 items
echo count($pager); // 4 pages of 50 for 160 items

// Sorting
foreach ($sorting->getAppliedSorts() as $sort) {
    echo $sort->getField(); // author.name
    echo $sort->getDirection(); // asc
}

// Filters
foreach ($filters->getAppliedFilters() as $filter) {

    if ($filter instanceof RangeFilter) {
        echo $filter->getField(); // published_at
        echo $filter->getLeft(); // 2019-01-01
        echo $filter->getRight(); // 2019-01-31
    }

    if ($filter instanceof SimpleFilter) {
        echo $filter->getField(); // category_id
        echo $filter->getValue(); // 12
    }

    if ($filter instanceof CollectionFilter) {
        echo $filter->getField(); // tags
        print_r($filter->getValues()); // ['foo', 'bar']
    }

    if ($filter instanceof StringMatchFilter) {
        echo $filter->getField(); // name
        echo $filter->getValue(); // 'foo'
        echo $filter->getOperator(); // StringMatchFilter::STARTS_WITH
        var_dump($filter->isNegated()); // true
    }
}

Now, we can ask our persistence system (Doctrine, ElasticSearch, Solr, 3rd-party API, ...) to return books:

From offset 100, limit to 50 items
Ordered by author.name (use your own logic to parse the field path)
Published between 2019-01-01 and 2019-01-31
In category id 12
Matching tag foo OR bar (AND clauses can also be set)
But their names MUST NOT start by foo.

Translating these value objects to query your database or API is now up to you! OpenCubes provides no bridge for the moment, but maybe in a near future.

Customization

Each component comes with a lot of customization possibilities (query parameters, default settings, ...).

HATEOAS

OpenCubes brings HATEOAS to your application by providing links for each component:

Page / PageSize links
Apply / remove sort link
Apply / remove filter
...

Each native component comes with a default JSON serialization which exposes the appropriate Urls. Being JSONserializable is not mandatory for your own components, it has been designed for a ready-to-use implementation. Different serializations can be achieved through your favourite serializer (Symfony / JMS to name a few).

Dive into components

Installation

OpenCubes is still at its early stage of development and subject to breaking changes.

Feel free to contribute or report any issue.

composer require bentools/opencubes:1.0.x-dev

Tests

./vendor/bin/phpunit

License

MIT.

bentools / opencubes

Maintainers

Details