khalyomede/odata-query-parser

Parse OData v4 query strings.

v0.1.0 2019-12-05 23:01 UTC

This package is auto-updated.

Last update: 2020-09-06 20:19:58 UTC


README

Parse OData v4 query strings.

Packagist Version Packagist PHP from Packagist Build Status Maintainability Known Vulnerabilities

Summary

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

Installation

Add the package to your dependencies:

composer require khalyomede/odata-query-parser

Examples

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).