Download the PHP package gam6itko/spiral-validator-manticore-search without Composer

spiral-validator-manticore-search

Manticore Search full-text query syntax checker for spiral/validator.

Validates the structure of a Manticore full-text query (extended query syntax) before it is stored or executed. Useful when a query is typed in by hand — by an administrator, a content editor, an API client — and executed later: a broken expression is rejected with a validation error on input instead of throwing a query error somewhere deep in the request that runs it.

The checker is a small hand-written lexer plus a recursive-descent parser. It needs no connection to a Manticore instance and performs no queries.

Requirements

• PHP >= 8.3
• spiral/validator ^1.7 (part of spiral/framework 3.x)

Installation

Registration

Add the checker to the checkers section of app/config/validator.php:

Or register it from a bootloader:

Usage

The checker exposes a single rule — manticore::query. Its optional argument is the list of full-text fields the @ operator is allowed to reference:

Without the field list only the syntax of @ is checked, not the field names:

The rule is deliberately narrow: an empty string and non-string values are passed through, so combine it with notEmpty / string::* when those matter. The error message key is query, the default message is [[Invalid search query syntax.]].

The checker can also be used on its own, outside of the validator:

What is validated

Structure only, never meaning:

• quotes " and parentheses ( ) are balanced;
• binary operators (|, <<, NEAR/N, MAYBE, SENTENCE, PARAGRAPH) have an operand on both sides, and neither operand consists of negations only — Manticore rejects a | -b, -a << b, a | (-b) as non-computable, but accepts a -b | c and a | (-b c);
• unary NOT (- / !) has an operand, and the query is not made of negations only;
• ~N and /N appear only right after a closing phrase quote, /N also as part of NEAR/N — anywhere else ~ and / are a syntax error for Manticore (price/rate, http://foo.bar, word~2, "a b"~5~5);
• the numeric argument of ~N / /N ends the term: only whitespace or the start of another operator (|, !, (, ), ", @) may follow it, so "a b"~2 c and "a b"~2|c are fine while "a b"~2a, "a b"~2-c, "a b"~2.c and "a b"~2* are rejected;
• ! is the NOT operator in any position, not just at the start of a term: word! and word!! are rejected (NOT without an operand), a!b reads as a without b;
• - is the NOT operator unless the character before it is a letter or a digit, where it is a literal instead: some-one, e-mail and 2024-05- are ordinary words, a--b and a,-b read as a without b, while a--, 100$- and C++- are a NOT left without an operand — rejected;
• the numeric argument of ~N / /N / NEAR/N / @field[N] is a positive integer;
• @field / @(f1,f2) / @!field / @field[N] refers to a known field, when the field list is given;
• a term made of positional markers only (^, $, =, *) does not count as a positive term: ^ is rejected, word ^ is accepted.

The reference implementation is Manticore's own parser: whatever the checker accepts, the daemon must be able to parse without an error. The rules were calibrated by running a corpus of queries through SELECT ... WHERE MATCH(?) against manticore 28.4.4; that corpus is the test suite.

In a few corner cases the checker is stricter than Manticore, where the daemon tolerates input that cannot match anything: an empty group (), a lone @, @field[abc], a dangling \ at the end of the string, a negation whose operand is a term made of separators only (a -.). Each of those is a plain typo, and a validation error is more useful than an empty result set. See provideStricterThanManticore() in the test suite for the full list.

What the checker does not do: it does not check that terms exist in the index, does not evaluate the query, and does not touch non-full-text parts of a SELECT (attribute filters, ORDER BY, OPTION) — it only looks at what goes inside MATCH().

Testing

Links

• Manticore Search: extended query syntax
• spiral/validator — documentation
• spiral/framework — documentation

License

MIT. See LICENSE.