Query Translator Laravel Package

Getting Started

First Steps

1. Installation

   composer require netgen/query-translator
   

   Register the service provider in config/app.php under providers:

   Netgen\QueryTranslator\QueryTranslatorServiceProvider::class,
   

2. Basic Usage Import the translator and parse a query string:

   use Netgen\QueryTranslator\QueryTranslator;
   
   $translator = app(QueryTranslator::class);
   $ast = $translator->parse('title:laravel AND (tags:php OR tags:framework)');
   

3. First Use Case: Search Query Parsing Use the AST (Abstract Syntax Tree) to build a structured query for Elasticsearch, SQL, or custom logic:

   $query = $translator->parse('price > 100 AND stock > 0');
   $sql = $query->toSql(); // Hypothetical method (see implementation patterns)
   

Implementation Patterns

1. Query Parsing & AST Manipulation

• Parse Complex Queries The package converts human-readable search queries into an AST for programmatic manipulation:

  $ast = $translator->parse('(name:john OR name:doe) AND age > 30');
  $ast->getChildren(); // Traverse nodes
  

• Custom Node Processing Extend functionality by adding custom node types or modifiers:

  $ast->addModifier('boost', 2.0); // Example: Boost relevance
  

2. Integration with Search Engines

• Elasticsearch Example Convert AST to Elasticsearch DSL:

  $query = $translator->parse('title:laravel AND tags:php');
  $elasticsearchQuery = $query->toElasticsearchQuery();
  

• SQL Generation (Hypothetical) If extending for SQL, map AST nodes to WHERE clauses:

  $sql = "WHERE (title LIKE '%laravel%' AND tags LIKE '%php%')";
  

3. Workflow: Building a Search API

1. Parse User Input

   $query = $translator->parse(request('q'));
   

2. Apply Business Logic

   if ($query->hasModifier('boost')) {
       $query->adjustBoost();
   }
   

3. Execute Against Data Layer

   $results = $searchService->search($query->toElasticsearchQuery());
   

4. Reusable Components

• Query Validation Check for unsupported syntax early:

  if (!$translator->isValid('invalid:query')) {
      abort(400, 'Invalid query syntax');
  }
  

• Query Caching Cache parsed ASTs for repeated queries:

  $cacheKey = md5($queryString);
  $ast = cache()->remember($cacheKey, now()->addHours(1), fn() => $translator->parse($queryString));
  

Gotchas and Tips

Pitfalls

1. Unsupported Operators

   • The package defaults to Lucene-like syntax (e.g., AND, OR, NOT). Custom operators (e.g., >, <) may require extension.
   • Fix: Extend Netgen\QueryTranslator\Parser\TokenStream or use QueryTranslator::setCustomOperators().

2. Performance with Complex Queries

   • Deeply nested queries (e.g., ((a AND b) OR (c AND d))) can bloat the AST.
   • Tip: Use QueryTranslator::setMaxDepth() to enforce limits.

3. Case Sensitivity

   • Field names (e.g., title:laravel) are case-sensitive by default.
   • Fix: Normalize fields in preprocessing:

     $queryString = strtolower($queryString);
     

4. Deprecated Methods

   • The package was last updated in 2022. Check for breaking changes if upgrading from older versions.

Debugging Tips

• Inspect AST Structure

  dd($ast->toArray()); // Visualize the parsed tree
  

• Enable Verbose Parsing

  $translator->setDebug(true); // Logs parsing steps
  

Extension Points

1. Custom Node Types Add support for domain-specific syntax (e.g., range:10..20):

   $translator->addNodeType('range', RangeNode::class);
   

2. Post-Processing Hooks Modify the AST after parsing:

   $ast->on('postParse', function ($ast) {
       $ast->rewriteFieldNames(fn($name) => strtolower($name));
   });
   

3. Integration with Laravel Scout Override Scout’s query builder to use the translator:

   public function toScoutQuery()
   {
       $ast = app(QueryTranslator::class)->parse($this->query);
       return $ast->toScoutQuery();
   }
   

Configuration Quirks

• Default Field Handling The package assumes field:value syntax. For single-field queries (e.g., laravel), configure a default field:

  $translator->setDefaultField('title');
  

• Locale-Specific Syntax Override tokenizers for non-English queries (e.g., AND → &&):

  $translator->setLocale('de_DE');