Parse OData v4 query strings.
I needed to only parse query strings to convert OData v4 commands into an understandable array that I could use to make a Laravel package to offer a way to automatically use Eloquent to filter the response according to this parsed array of OData v4 command.
As I did not see a package exclusively dealing with parsing the query strings, and saw that some people worked on their own without open sourcing it, I decided I would start one myself.
- Parses an URL and returns an array
- Supports
$select
,$top
,$skip
,$orderby
,$count
- Partial support for
$filter
(see Known issues section) - You can use a parse mode that let you parse these keywords without prepending
$
- PHP >= 7.2.0
- Composer
Add the package to your dependencies:
composer require khalyomede/odata-query-parser
In this example, we will use the $select
OData query string command to filter the fields returned by our API.
use Khalyomede\OdataQueryParser;
$data = OdataQueryParser::parse('https://example.com/api/user?$select=id,name,age');
If you inspect $data
, this is what you will get:
[
"select" => [
"id",
"name",
"age"
]
]
In this example, we will use a unique feature of this library: to be able to not specify any dollar, while still being able to use the OData v4 URL query parameter grammar.
use Khalyomede/OdataQueryParser;
$data = OdataQueryParser::parse("https://example.com/api/user?select=id,name,age", $withDollar = false);
If you inspect $data
, this is what you will get:
[
"select" => [
"id",
"name",
"age"
]
]
OdataQueryParser::parse(string $url, bool $withDollar = true): array;
parameters
- string
$url
: The URL to parse the query strings from. It should be a "complete" or "full" URL, which means thathttps://example.com
will pass whileexample.com
will not pass - bool
$withDollar
: Set it to false if you want to parse query strings without having to add the$
signs before each keys.
returns
An associative array:
return = [
string? "select" => array<string>,
string? "count" => bool,
string? "top" => int,
string? "skip" => int,
string? "orderBy" => array<OrderBy>,
string? "filter" => array<Filter>
];
OrderBy = [
string "property" => string,
string "direction" => Direction
]
Direction = "asc" | "desc"
Filter = [
string "left" => string,
string "operator" => string,
string "right" => mixed
]
throws
InvalidArgumentException
- If the parameter
$url
is not a valid URL (see the parameter description to know what is a valid URL) - If the
$top
query string value is not an integer - If the
$top
query string value is lower than 0 - If the
$skip
query string value is not an integer - If the
$skip
query string value is lower than 0 - If the direction of the
$orderby
query string value is neitherasc
ordesc
- If the parameter
$filter
command will not parseor
and functions (likecontains()
ofsubstringof
), because I did not focused on this for the moment (the parser for$filter
is too simplist, I should find a way to create an AST).