Weave Code
Query Parser Laravel Package
gdbots/query-parser
A PHP library for parsing query strings into a structured AST, with support for boolean operators, fielded terms, grouping, ranges, and wildcards. Useful for validating and translating user search input into database queries.
gdbots/query-parser is a PHP library for converting human-readable query strings into a structured abstract syntax tree (AST). It handles fielded searches, boolean expressions, phrases, and grouped clauses, making it useful for search interfaces, filtering, and translating user input into backend-specific query formats.
- Parses fielded, boolean, phrase, and grouped query syntax
- Produces a traversable AST for validation and transformation
- Respects operator precedence and nested expressions
- Framework-agnostic with Composer support
- Extensible node model for custom query processing
Frequently asked questions about Query Parser
- What does gdbots/query-parser do?
- gdbots/query-parser is a standalone PHP library that converts Lucene-style query strings into structured query objects. It parses terms, quoted phrases, hashtags, mentions, fielded terms, ranges, grouping, and boolean operators. In a Laravel app it fits as an input-normalization layer between the HTTP request and your search backend, not as a database or search engine itself.
- How do I install gdbots/query-parser in Laravel?
- Install it with Composer using composer require gdbots/query-parser; the package is PSR-4 autoloaded and the context describes no runtime services, schema changes, or queue or cache requirements. There is no Laravel-specific service provider or configuration described, so you instantiate the parser directly or bind it in your own service container. Run the install in a throwaway branch first so you can see the full dependency graph before adopting it.
- Is gdbots/query-parser compatible with Laravel 10 and 11 on PHP 8.2+?
- Laravel 10 and 11 are framework constraints, not parser constraints: the library is framework-agnostic PHP, so the real question is its PHP version requirement and transitive Symfony or gdbots pins. The last release was 2021-12-05, so it may declare PHP 7.x-era constraints and may never have been tested on PHP 8.2 through 8.4. Verify with composer require gdbots/query-parser in a throwaway Laravel 10 or 11 skeleton and inspect composer why-not before any design work.
- Does gdbots/query-parser require gdbots/pbj or gdbots message infrastructure?
- That is a key pre-adoption check, not something to assume. The context flags gdbots/pbj and Symfony pins as the most likely dependency conflicts, and it also asks whether the parser output is a neutral value object or a gdbots-specific message type. Inspect composer show gdbots/query-parser and the node classes after install; if it pulls in gdbots message infrastructure, map the output immediately into your own DTOs so vendor concepts do not leak into your domain.
- What does the parsed output look like, and should I type-hint vendor classes?
- The parser emits a structured representation of the query, including terms, phrases, hashtags, mentions, fielded terms, ranges, grouping, and boolean operators, rather than a flat list of tokens. Treat those nodes as an implementation detail: define your own ParsedQuery DTO and a QueryParser contract, then map vendor nodes into your types at the boundary. Avoid type-hinting gdbots classes in controllers, form requests, or jobs so a future fork or replacement is a swap rather than a rewrite.
- How do I use gdbots/query-parser with Laravel Scout, Eloquent, or Meilisearch?
- The package does not query Eloquent, Scout, Meilisearch, Elasticsearch, or Algolia; it only parses the string. Parse once into your canonical DTO, then compile that representation to the target backend, such as Scout or Meilisearch filters, Elasticsearch query DSL, or Eloquent where clauses. That adapter is yours to write regardless of vendor, so the parser is a head start on input handling rather than a search integration.
- Can I add custom operators or extend the grammar in gdbots/query-parser?
- The library already covers fielded terms, boolean operators, quoted phrases, ranges, and grouping, so first confirm whether the operator you need is already supported. For genuinely custom syntax, the context flags grammar extensibility as an open question: check whether the parser exposes configuration or hooks before planning on it. If it does not, you can vendor or fork the source under its Apache-2.0 license and retain attribution, but budget for that maintenance.
- Is gdbots/query-parser safe for untrusted user input and pathological queries?
- It is a parser, not a sanitizer or query executor, so it does not by itself make user input safe. The context specifically warns that regex-based tokenizers can suffer backtracking blowups on long or pathological strings, so enforce a maximum query length and test adversarial inputs. Always compile parsed output into parameterized or structured backend queries rather than concatenating raw input back into a query string.
- How should I test a Laravel integration with gdbots/query-parser?
- Because the parser is stateless and has no runtime services, most testing is plain unit testing: feed query strings and assert the resulting DTOs. Add characterization or golden-file tests for the grammar you rely on, including boolean precedence, quoted phrases, ranges, and fielded terms, so you notice behavior changes if you patch or replace the library. Keep one integration test for the adapter that compiles your DTOs into the real backend query, and avoid mocking the parser itself.
- Is gdbots/query-parser maintained, and what are alternatives?
- Maintenance risk is the main concern: the last release was 2021-12-05, the project has about 30 stars, zero listed dependents, and a single maintaining organization. The code may be functionally complete for a stable grammar, but plan for abandonment by binding it behind your own interface and keeping a fork-or-replace path. If you only need whitespace and quoted-phrase splitting, a small in-house tokenizer may be less dead weight; if you need full Lucene-style syntax, compare it with the query-string parsing built into your search engine or another maintained parser.
Weaver
How can I help you explore Laravel packages today?