Unmaintained notice

Be aware I am not longer able to provide updates regularily. Please check this repository for a more up-to-date version: https://github.com/Globy-App/odata-query-parser.

odata-query-parser

Parse OData v4 query strings.

Summary

• About
• Features
• Requirements
• Installation
• Examples
• API
• Known issues

About

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.

Features

• 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 $

Requirements

• PHP >= 7.2.0
• Composer

Installation

Add the package to your dependencies:

composer require khalyomede/odata-query-parser

Examples

• 1. Use $select to filter on some fields
• 2. Use non dollar syntax

1. Use $select to filter on some fields

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('http://example.com/api/user?$select=id,name,age');

If you inspect $data, this is what you will get:

[
  "select" => [
    "id",
    "name",
    "age"
  ]
]

2. Use non dollar syntax

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("http://example.com/api/user?select=id,name,age", $withDollar = false);

If you inspect $data, this is what you will get:

[
  "select" => [
    "id",
    "name",
    "age"
  ]
]

API

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 that http://example.com will pass while example.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 neither asc or desc

Known issues

• $filter command will not parse or and functions (like contains() of substringof), 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).