Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/railken/search-query
A library that converts a query string into a tree object
https://github.com/railken/search-query
api composer php query search tree
Last synced: about 1 month ago
JSON representation
A library that converts a query string into a tree object
- Host: GitHub
- URL: https://github.com/railken/search-query
- Owner: railken
- License: mit
- Created: 2017-10-15T11:00:11.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2024-03-27T19:46:47.000Z (9 months ago)
- Last Synced: 2024-07-11T03:12:13.940Z (6 months ago)
- Topics: api, composer, php, query, search, tree
- Language: PHP
- Homepage:
- Size: 615 KB
- Stars: 3
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Search Query
[](https://github.com/railken/search-query/actions)
Converts a simple expression (e.g. 'x eq 1 or y gt 2') into a tree object.
This can be pretty usefull when building the API endpoint for a search.
## Requirements
PHP 7.1 or later.
## Composer
You can install it via [Composer](https://getcomposer.org/) by typing the following command:
```bash
composer require railken/search-query
```
## Demo
## Usage
A simple usage looks like this:
```php
use Railken\SQ\QueryParser;
use Railken\SQ\Resolvers as Resolvers;
$parser = new QueryParser();
$parser->addResolvers([
new Resolvers\ValueResolver(),
new Resolvers\KeyResolver(),
new Resolvers\GroupingResolver(),
new Resolvers\NotEqResolver(),
new Resolvers\EqResolver(),
new Resolvers\LteResolver(),
new Resolvers\LtResolver(),
new Resolvers\GteResolver(),
new Resolvers\GtResolver(),
new Resolvers\CtResolver(),
new Resolvers\SwResolver(),
new Resolvers\NotInResolver(),
new Resolvers\InResolver(),
new Resolvers\EwResolver(),
new Resolvers\NotNullResolver(),
new Resolvers\NullResolver(),
new Resolvers\AndResolver(),
new Resolvers\OrResolver(),
new Resolvers\TextResolver(),
]);
$result = $query->parse('x eq 1 or y > 1');
```
The result formatted in json of `$result`:
```json
{
"type": "Railken\\SQ\\Nodes\\OrNode",
"value": "OR",
"childs": [
{
"type": "Railken\\SQ\\Nodes\\EqNode",
"value": "EQ",
"childs": [
{
"type": "Railken\\SQ\\Nodes\\KeyNode",
"value": "x"
},
{
"type": "Railken\\SQ\\Nodes\\ValueNode",
"value": "1"
}
]
},
{
"type": "Railken\\SQ\\Nodes\\GtNode",
"value": "GT",
"childs": [
{
"type": "Railken\\SQ\\Nodes\\KeyNode",
"value": "y"
},
{
"type": "Railken\\SQ\\Nodes\\ValueNode",
"value": "1"
}
]
}
]
}
```
## Nodes
### Key node
All alphanumeric (starting with alphabetic character) are converted as ```KeyNode```. Other characters allowed: ```_```
Examples:
```
created_at
```
### Value node
All numbers and strings are converted as ```ValueNode```. The delimiter of strings can be either ```'``` or ```"```
Examples:
```
"An apple"
30.20
```
### Group node
All round parenthesis create a group node ```( ... )```. Of course a nested group can be made. If a parenthesis is missing an exception will be thrown
Examples:
```
(x or y) and z
((x > 10 and w) or (y > 5 and f)) and z
```
### AND, OR
This operators requires a ```Node``` before and after, otherwise an exception will be thrown.
Can be expressed as literals (and, or) or as symbols (&&, ||)
**Important**: If a parent group is defined and the LogicNode is the only child, the LogicNode will take the place of the GroupNode.
Examples:
```
x or y || z
x and y && z
```
### EQ, NOT_EQ, GT, GTE, LT, LTE
All these operators requires ```KeyNode``` or a ```ValueNode``` before and afters.
Can be expressed as literals (eq, not eq, gt, gte, lt, lte) or as symbols (=, !=, >, >=, < <=)
Examples:
```
x eq 1
x = 1
x gt 1
x > 1
x gte 1
x >= 1
x lt 1
x < 1
x lte 1
x <= 1
```
Comparison can be also made between two keys
Examples:
```
x eq y
```
### CT, SW, EW
These operators will handle comparison with strings: contains, start with and end with.
Examples:
```
description ct "a random phrase"
description sw "the text must start with this"
description ew "the text must end with this"
```
### NULL, NOT NULL
These operators don't require a node after the operator.
```
deleted_at is null
deleted_at is not null
```
## Custom resolver
As you already saw, in order to parse the query you have to add the resolvers.
So you are free to add any resolvers you want, but pay attention to the order: KeyValue and NodeValue are the foundation for all the resolvers, so be carefull.
Here's an example of custom resolver and node
CustomResolver.php
```php
addResolvers([
new \App\SQ\Resolvers\CustomResolver(),
});
```
If you have a more complicated node to resolve simply add the method resolve to the CustomResolver.
```php
addResolvers([
new Resolvers\CustomResolver(function ($node) {
if($node instanceof Nodes\KeyNode) {
$node->setValue("myCustomPrefix.".$node->getValue());
}
}),
]);
```
## License
Open-source software licensed under the [MIT license](https://opensource.org/licenses/MIT).