Custom Adapters and Visitors
Create output formats with AST visitors, transform query trees, and preserve source positions, quoting, and default metadata.
For a database, search engine, or another execution backend, consume SearchParser::compile(), which resolves groups, terms, and negation. Implement QueryAdapterInterface to produce another AST output format. Register a creator with extend() and select it by name:
use HosmelQ\SearchSyntaxParser\Adapter\QueryAdapterInterface;
use HosmelQ\SearchSyntaxParser\Adapter\StringAdapter;
use HosmelQ\SearchSyntaxParser\AST\Node\NodeInterface;
use HosmelQ\SearchSyntaxParser\SearchParser;
final readonly class QueryEnvelopeAdapter implements QueryAdapterInterface
{
public function build(NodeInterface $ast): array
{
return ['query' => new StringAdapter()->build($ast)];
}
}
$parser = SearchParser::query('coffee tea');
$parser->extend('envelope', fn (): QueryEnvelopeAdapter => new QueryEnvelopeAdapter());
$result = $parser->build('envelope');The result is ['query' => 'coffee AND tea']. Creators receive no arguments; capture the parser if the adapter needs field metadata.
Custom adapters receive a non-null tree. When parsing returns null, build() resolves the selected adapter but does not call it. Unknown adapter names still fail.
Visit nodes
Every node implements getType(), getSpan(), and accept(VisitorInterface $visitor). Implement these visitor methods to handle each node:
| Method | Node type |
|---|---|
visitBinaryOperator() | AND or OR with left and right children. |
visitComparison() | A field, operator, and scalar value. |
visitExists() | An existence check. |
visitIn() | A field and list of values. |
visitRange() | A field and inclusive bounds. |
visitTerm() | A bare text term. |
visitUnaryOperator() | NOT with an operand. |
visitWildcard() | Literal segments separated by wildcard operators. |
Call accept() on children to traverse them. Field nodes retain external names, including complete dynamic keys. A wildcard's field is null for a bare term. Compact and bracket ranges share RangeNode.
AbstractAdapter provides getInternalFieldName() when constructed with a parser. Use getAllowedField() to retrieve field metadata, getTextMatch() for effective matching, and toStorage() for backend values. The clause compiler handles these value and operator conversions for scalar and array field schemas.
ArrayAdapter is extensible, so you can override one visitor method while keeping the rest of its representation. Adapters must implement case-insensitive text comparisons and map accepted fields to trusted backend identifiers.
Rewrite a tree
Extend NodeTransformer to replace selected nodes. Its default implementation recursively transforms children and returns an equivalent tree:
use HosmelQ\SearchSyntaxParser\Adapter\StringAdapter;
use HosmelQ\SearchSyntaxParser\AST\Node\NodeInterface;
use HosmelQ\SearchSyntaxParser\AST\Node\TermNode;
use HosmelQ\SearchSyntaxParser\AST\Visitor\NodeTransformer;
use HosmelQ\SearchSyntaxParser\SearchParser;
final class UppercaseTerms extends NodeTransformer
{
public function visitTerm(TermNode $node): NodeInterface
{
return new TermNode(mb_strtoupper($node->getValue()), $node->isQuoted(), $node->getSpan());
}
}
$tree = SearchParser::query('coffee OR NOT tea')->parse();
$rewritten = new UppercaseTerms()->transform($tree);
$text = new StringAdapter()->build($rewritten);The result is COFFEE OR NOT TEA. Unchanged readonly leaves are shared; rebuilt groups retain their spans.
When replacing nodes, preserve the metadata they expose:
- Pass
isDefault()to replacement comparisons, lists, exists checks, and unary nodes. - Preserve
isQuoted()on terms and comparisons, and each item's quote flag on lists. - Pass
InNode::getPositions()so array storage conversion keeps the written item positions.
Negation normal form
SearchParser::compile() applies NegationNormalFormTransformer automatically. Use the transformer directly for AST rewrites. It moves NOT directly around leaves, applies De Morgan's laws, and removes double negation. Not-equal comparisons, lists, and wildcards become NOT around their positive form.
use HosmelQ\SearchSyntaxParser\Adapter\StringAdapter;
use HosmelQ\SearchSyntaxParser\AST\Visitor\NegationNormalFormTransformer;
use HosmelQ\SearchSyntaxParser\SearchParser;
$tree = SearchParser::query('NOT (price:>10 OR status:!=open)')
->allowedFields(['price', 'status'])
->parse();
$normalized = new NegationNormalFormTransformer()->transform($tree);
$text = new StringAdapter()->build($normalized);The result is NOT price:>10 AND status:open. parse() does not run this transformer automatically.
Ordering comparisons retain their operators. NOT price:>10 includes missing prices for a nullable field, so replacing it with a plain price:<=10 would change the result. For a multi-valued field, negation means no element matches, including records with no elements.
Adapters must apply set-complement semantics, including missing columns, keys, or relations. SQL's ordinary NOT or NOT LIKE is not sufficient for nullable values.
Build LIKE patterns
Query\TextPattern preserves literal segments until a backend renders them:
use HosmelQ\SearchSyntaxParser\AST\Node\WildcardNode;
use HosmelQ\SearchSyntaxParser\Query\TextPattern;
use HosmelQ\SearchSyntaxParser\Validation\TextMatch;
$wildcard = new WildcardNode('title', '=', ['co', 'fee']);
$pattern = TextPattern::fromWildcard($wildcard)->toLike();
$prefix = TextPattern::forMatch('50%', TextMatch::Prefix)->toLike();$pattern is co%fee, and $prefix is 50!%%. Bind these values and use LIKE ? ESCAPE '!'. The helper escapes literal %, _, and !; quoted asterisks remain literal text.
new TextPattern([$literal]) represents literal text. forMatch() supports exact, prefix, and contains modes. Whole-word matching needs a backend operation, so TextMatch::Words throws InvalidArgumentException.
toLike() accepts a custom escape character. It must be one Unicode character other than % or _, and the backend must use the same character in its ESCAPE clause.
Extend field validation
Override Field::accepts(string $name): bool to narrow accepted public names, calling the parent to retain dynamic key validation. keyOf($name) returns the suffix of a matching pattern name, including an empty suffix, or null for a different prefix or an exact field; extraction does not validate the key.
Override Field::assertValidConfiguration(): void to reject invalid backend targets when fields are registered. Call the parent to preserve core configuration checks. Both methods are public extension points.
Read source positions
getSpan() returns a readonly Span with offset and length, measured in Unicode code points from the original query. These are the same coordinates used by exception positions:
use HosmelQ\SearchSyntaxParser\SearchParser;
$node = SearchParser::query(' title:"Café"')->allowedFields(['title'])->parse();
$span = $node->getSpan();The offset is 2 and the length is 12. Quotes, trailing wildcards, and closing range brackets are included. Binary nodes cover their operands and consumed group delimiters; unary nodes start at NOT or minus. A group's inner node covers its inner content. Expanded wildcard-list nodes cover the whole field clause.
Node constructors accept an optional span. Programmatic and default-generated nodes can have null spans, so use isDefault() to identify defaults. Neither built-in adapter emits spans. Compiled clauses retain the leaf's offset as position.
Report adapter errors
Extend SearchSyntaxException when an adapter needs a structured query error:
use HosmelQ\SearchSyntaxParser\Exception\ErrorReason;
use HosmelQ\SearchSyntaxParser\Exception\SearchSyntaxException;
final class UnsupportedQueryException extends SearchSyntaxException {}
$exception = new UnsupportedQueryException(
'Ranges are not supported by this adapter.',
ErrorReason::OperatorNotAllowed,
['field' => 'price', 'operation' => 'ranges'],
0,
);The constructor accepts a message, reason, parameters, and optional source position. Use getMessageKey() and getMessageParameters() for application translations; see error handling.