mrcnpdlk/url-search-parser

URL search parser - filter & search params manipulation

v2.7.0 2022-05-23 11:59 UTC

Requires

• php: >=7.2
• ext-json: *

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3
• jangregor/phpstan-prophecy: ^0
• phpstan/phpstan: ^0
• phpstan/phpstan-phpunit: ^0
• phpunit/php-code-coverage: ^7
• phpunit/phpunit: ^8

MIT

• Marcin Pudełek

• rest
• parser
• filtering
• searching

README

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