mrcnpdlk/url-search-parser

URL search parser - filter & search params manipulation

mrcnpdlk/url-search-parser

, _(*1)

, _(*2)

, _(*3)

, _(*4)

Contents

This boundle has been created for parsing advanced queries to easy-to-use objects., _(*5)

Based on https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#advanced-queries, _(*6)

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, _(*7)

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:, _(*8)

• 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:, _(*9)

• 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, _(*10)

In case using not allowed operator mrcnpdlk\Lib\UrlQueryParser\Exception\InvalidParamException is thrown., _(*11)

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

Limit

Example:, _(*12)

• GET /messages?limit=20 - limitation;

/**
 * @var $iLimit integer|null
 */
$iLimit = $oParser->getLimit(10); // in NULL default=10

Page

Example:, _(*13)

• 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:, _(*14)

• 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., _(*15)

Example:, _(*16)

• 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, _(*17)

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., _(*18)

License

Copyright (c) 2018 Marcin Pudełek / mrcnpdlk, _(*19)

This project is licensed under the MIT License - see the LICENSE file for details, _(*20)

, _(*21)