https://github.com/khalyomede/odata-query-parser
Parse OData v4 query strings.
https://github.com/khalyomede/odata-query-parser
odata-query-parser php
Last synced: about 2 months ago
JSON representation
Parse OData v4 query strings.
- Host: GitHub
- URL: https://github.com/khalyomede/odata-query-parser
- Owner: khalyomede
- License: mit
- Created: 2019-12-04T22:24:00.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-09-07T12:45:09.000Z (9 months ago)
- Last Synced: 2025-04-02T01:35:16.098Z (about 2 months ago)
- Topics: odata-query-parser, php
- Language: PHP
- Homepage: https://packagist.org/packages/khalyomede/odata-query-parser
- Size: 19.5 KB
- Stars: 2
- Watchers: 2
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://github.com/Globy-App/odata-query-parser).
# odata-query-parser
Parse OData v4 query strings.
[](https://packagist.org/packages/khalyomede/odata-query-parser) [](https://github.com/khalyomede/odata-query-parser/blob/master/LICENSE) [](https://github.com/khalyomede/odata-query-parser/blob/master/composer.json#L14) [](https://travis-ci.com/khalyomede/odata-query-parser) [](https://codeclimate.com/github/khalyomede/odata-query-parser/maintainability) [](https://snyk.io/test/github/khalyomede/odata-query-parser?targetFile=composer.lock)
## Summary
- [About](#about)
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Examples](#examples)
- [API](#api)
- [Known issues](#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](https://stackoverflow.com/questions/14145604/parse-odata-query-uri-into-php-array), 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](#known-issues) section)
- You can use a parse mode that let you parse these keywords without prepending `$`
## Requirements
- PHP >= 7.2.0
- [Composer](https://getcomposer.org/)
## Installation
Add the package to your dependencies:
```bash
composer require khalyomede/odata-query-parser
```
## Examples
- [1. Use \$select to filter on some fields](#1-use-select-to-filter-on-some-fields)
- [2. Use non dollar syntax](#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.
```php
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:
```php
[
"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.
```php
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:
```php
[
"select" => [
"id",
"name",
"age"
]
]
```
## API
```php
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:
```php
return = [
string? "select" => array,
string? "count" => bool,
string? "top" => int,
string? "skip" => int,
string? "orderBy" => array,
string? "filter" => array
];
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).