spatie / elasticsearch-search-string-parser
Build Elasticsearch queries based of a query string
Fund package maintenance!
spatie
Installs: 20 423
Dependents: 0
Suggesters: 0
Security: 0
Stars: 47
Watchers: 4
Forks: 3
Open Issues: 0
Requires
- php: ^8.0
- elasticsearch/elasticsearch: ^7.12
- illuminate/collections: ^8.40|^9.0|^10.0
- spatie/elasticsearch-query-builder: ^1.0
Requires (Dev)
- brianium/paratest: ^6.2
- larapack/dd: ^1.1
- phpunit/phpunit: ^9.3|^10.0
- spatie/phpunit-snapshot-assertions: ^4.2
- vimeo/psalm: ^4.4
README
Parse custom search strings and execute them using ElasticSearch
This package allows you to convert a search string like foo bar status:active @john.doe
to its corresponding ElasticSearch request. Any custom directives like status:active
and @john.doe
can be added using regex and the spatie/elasticsearch-query-builder
. There's also basic support for grouping directives (e.g. group_by:project
) and providing auto-completion suggestions for certain directives.
use Elasticsearch\ClientBuilder; use Spatie\ElasticsearchStringParser\SearchQuery; $subjects = SearchQuery::forClient(ClientBuilder::create()) ->baseDirective(new SubjectBaseDirective()) ->patternDirectives( new CompanyDirective(), new UserDirective(), ) ->search('deadly neurotoxin company:aperture @glados');
In the example above, an ElasticSearch request is executed with the appropriate parameters set to search for results with the given company (aperture
), user (glados
) and subject string (deadly neurotoxin
). The returned value is a \Spatie\ElasticsearchStringParser\SearchResults
object that contains search results and suggestions for the applied directives.
Support us
We invest a lot of resources into creating best in class open source packages . You can support us by buying one of our paid products.
We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.
Installation
You can install the package via composer:
composer require spatie/elasticsearch-search-string-parser
How it works: directives
When creating a search string parser, you decide how each part of the search string is parsed by defining directives. When a directive is found in the search string, it is applied to the underlying ElasticSearch. Directives can be used to add basic match queries but also to add sorts, aggregations, facets, etc...
Let's dive into the inner workings of the package by dissecting an example search string and its parser:
$searchString = 'cheap neurotoxin company:aperture deadly @glados'; SearchQuery::forClient(ClientBuilder::create()) ->baseDirective(new SubjectBaseDirective()) ->patternDirectives( new CompanyDirective(), new UserDirective(), )->search($searchString);
A search string parser can have multiple PatternDirective
s and at most one BaseDirective
. In the example search string there are two pattern directives: company:aperture
and @glados
. These will be parsed by the CompanyDirective
and UserDirective
. The remaining string (cheap nearotoxin deadly
) will be processed by the base directive.
To do this, we'll loop over all configured pattern directives. Each patter directive has a regular expression it looks for. If one of the directives finds a match in the search string, it will be applied and the match will be removed from the search string. The process is then repeated for the next match or the next pattern directive.
Back to our example: the CompanyDirective
is configured to match company:(.*)
. In the example string, this regex pattern will match company:aperture
. This means the CompanyDirective
will be applied and a query for company_name="aperture"
will be added to the ElasticSearch builder. Finally, the directive is removed from the search string, leaving us with the following string:
cheap neurotoxin deadly @glados
As there are no other matches for the CompanyDirective
, we'll look for the UserDirective
next. The user directive will search for @(.*)
and thus match @glados
. The UserDirective
will now apply its queries to the ElasticSearch builder and remove the matches string. We're left with:
cheap neurotoxin deadly
There are no pattern directives left to apply. The entire remaining string is then passed to the SubjectBaseDirective
. This base directive then decides what to do with the remaining search string, for example, using it for a fuzzy search on the subject field.
Usage
$elasticsearch-search-string-parser = new Spatie\ElasticsearchStringParser(); echo $elasticsearch-search-string-parser->echoPhrase('Hello, Spatie!');
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.