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
Install the latest version with composer
composer require mrcnpdlk/url-search-parser
$oParser = new \Mrcnpdlk\Lib\UrlQueryParser\RequestParser($query);
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();
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();
Example:
GET /messages?limit=20
- limitation;
/**
* @var $iLimit integer|null
*/
$iLimit = $oParser->getLimit(10); // in NULL default=10
Example:
GET /messages?page=1
- pagination. Should be used withlimit
parameter;
/**
* @var $iPage integer|null
*/
$iPage = $oParser->getPage(1); // in NULL default=1
Example:
GET /messages?phrase=foo
- for easier filtering;
/**
* @var $sPhrase string|null
*/
$sPhrase = $oParser->getPhrase(); // if not set NULL ir returned
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
// 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);
$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
./vendor/bin/phpunit
- Marcin Pudełek - Initial work - mrcnpdlk
See also the list of contributors who participated in this project.
Copyright (c) 2018 Marcin Pudełek / mrcnpdlk
This project is licensed under the MIT License - see the LICENSE file for details