mrcnpdlk/url-search-parser

URL search parser - filter & search params manipulation

v2.6.0 2020-09-30 13:54 UTC

README

Latest Stable Version Latest Unstable Version Total Downloads Monthly Downloads License FOSSA Status

Scrutinizer Code Quality Code Coverage Build Status

Code Climate Issue Count

Build Status

Contents

This boundle has been created for parsing advanced queries to easy-to-use objects.

Based on https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#advanced-queries

  1. Installation
  2. Supported parameters
    1. Sort
    2. Filter
    3. Limit
    4. Page
    5. Phrase
    6. Others
  3. Usage

Installation

Install the latest version with composer

composer require mrcnpdlk/url-search-parser

Supported parameters

$oParser = new \Mrcnpdlk\Lib\UrlQueryParser\RequestParser($query); 

Sort

Generic parameter sort can be used to describe sorting rules. Accommodate complex sorting requirements by letting the sort parameter take in list of comma separated fields, each with a possible unary negative to imply descending sort order. Let's look at some examples:

  • GET /messages?sort=-createDate - Retrieves a list of messages in descending order of createDate;
  • GET /messages?sort=-type,createDate - Retrieves a list of messages in descending order of type. Within a specific type, older messages are ordered first;
/**
 * @var $oSort \Mrcnpdlk\Lib\UrlQueryParser\Criteria\Sort
 */
$oSort = $oParser->getSort();

Filter

Filtering is more complex then sorting. Array notation is used. Let's look at some examples:

  • GET /messages?filter[created][lt]=2018-06-01 - Retrieves a list of messages where createDate is lower than 2018-06-01;
  • GET /messages?filter[type][in]=urgent,warning,error - Retrieves a list of messages where type is urgent, warning or error;
  • GET /messages?filter[type][null] - Retrieves a list of messages where type is NULL;

Allowed operators: eq,lt,lte,gt,gte,like,llike,rlike,in,notin,null,notnull,regexp

In case using not allowed operator mrcnpdlk\Lib\UrlQueryParser\Exception\InvalidParamException is thrown.

/**
 * @var $oFilter \Mrcnpdlk\Lib\UrlQueryParser\Criteria\Filter
 */
$oFilter = $oParser->getFilter();

Limit

Example:

  • GET /messages?limit=20 - limitation;
/**
 * @var $iLimit integer|null
 */
$iLimit = $oParser->getLimit(10); // in NULL default=10

Page

Example:

  • GET /messages?page=1 - pagination. Should be used with limit parameter;
/**
 * @var $iPage integer|null
 */
$iPage = $oParser->getPage(1); // in NULL default=1

Phrase

Example:

  • GET /messages?phrase=foo - for easier filtering;
/**
 * @var $sPhrase string|null
 */
$sPhrase = $oParser->getPhrase(); // if not set NULL ir returned

Other params

Use getQueryParam() method.

Example:

  • GET /messages?foo=bar&baz=5 - additional params;
$sFoo = $oParser->getQueryParam('foo','string'); // return 'bar'
$sBaz = $oParser->getQueryParam('baz','int'); // return 5

Usage

// Two ways to get `query` argument for RequestParser constructor:
$query = parse_url($url, PHP_URL_QUERY); // OR
$query = $_SERVER['QUERY_STRING'];

$oParser = new \Mrcnpdlk\Lib\UrlQueryParser\RequestParser($query); 

Example

$url = 'https://api.expample.com?sort=id,-name&filter[isFoo][eq]=1&filter[age][gt]=12&page=3&limit=10&offset=20';
$query =  parse_url($url, PHP_URL_QUERY);
$oParser = new \Mrcnpdlk\Lib\UrlQueryParser\RequestParser($query);

print_r($oParser->getSort()->toArray());
print_r($oParser->getFilter()->toArray());
print_r($oParser->getLimit());
print_r($oParser->getPage());
print_r($oParser->getPhrase());

Result

Array
(
    [0] => mrcnpdlk\Lib\UrlQueryParser\Criteria\SortParam Object
        (
            [param] => id
            [direction] => ASC
        )

    [1] => mrcnpdlk\Lib\UrlQueryParser\Criteria\SortParam Object
        (
            [param] => name
            [direction] => DESC
        )

)
Array
(
    [0] => mrcnpdlk\Lib\UrlQueryParser\Criteria\FilterParam Object
        (
            [param] => isFoo
            [operator] => eq
            [sqlOperator] => =
            [value] => 1
        )

    [1] => mrcnpdlk\Lib\UrlQueryParser\Criteria\FilterParam Object
        (
            [param] => age
            [operator] => gt
            [sqlOperator] => >
            [value] => 12
        )

)
10 // limit
3  // page
20 // offset

Running the tests

./vendor/bin/phpunit

Authors

  • Marcin Pudełek - Initial work - mrcnpdlk

See also the list of contributors who participated in this project.

License

Copyright (c) 2018 Marcin Pudełek / mrcnpdlk

This project is licensed under the MIT License - see the LICENSE file for details

FOSSA Status