README

A pure-PHP parser for the Lucene query syntax, plus a Laravel adapter that compiles a Lucene query string straight into a safe, parameterized SQL WHERE on your existing Eloquent models — no separate search index, no sync, no infrastructure.

Article::query()
    ->where('active', true)
    ->whereMatch('(title:laravel OR body:lucene) AND -status:archived')
    ->orderBy('published_at')
    ->paginate();

Every Lucene group becomes one nested where(fn …) closure, every value is a PDO binding, and every column is a whitelisted identifier — so you can hand it an untrusted end-user search string without opening a SQL-injection hole.

Why this exists

The PHP ecosystem has plenty of Lucene query builders and several "Laravel + Lucene" packages — but they all bolt on a separate ZendSearch/Elasticsearch index you have to populate and keep in sync. None of them compile a Lucene string directly into a WHERE clause against the columns you already have. This package does exactly that.

Requirements

• PHP ^8.3
• Laravel ^12.0 | ^13.0 (for the Eloquent adapter; the parser core is framework-agnostic)

Installation

composer require prometa/laravel-lucene

The service provider is auto-discovered. Publish the config if you want to tweak the defaults:

php artisan vendor:publish --tag=lucene-config

Quick start

Declare the searchable surface of a model with the Searchable trait and a $lucene array, then call whereMatch():

use Illuminate\Database\Eloquent\Model;
use Prometa\Lucene\Laravel\Concerns\Searchable;

class Article extends Model
{
    use Searchable;

    protected array $lucene = [
        'fields' => [
            'title'        => 'text',                 // LIKE %value%
            'body'         => 'text',
            'status'       => 'exact',                // = value
            'views'        => 'number',               // numeric ranges / compare
            'published_at' => 'date',                 // date ranges
            'author'       => 'relation:author.name', // whereHas('author', name LIKE …)
        ],
        'default'  => ['title', 'body'],              // fields searched for a bare term
        'operator' => 'or',                           // how bare clauses combine (or | and)
    ];
}

Article::query()->whereMatch('title:hobbit')->get();
Article::query()->whereMatch('status:published AND views:[1000 TO *]')->get();
Article::query()->whereMatch('author:tolkien -status:draft')->get();
Article::query()->where('featured', true)->orWhereMatch('"the shining"')->get();

whereLucene() / orWhereLucene() are identical aliases if you prefer to name the backing technology at the call site.

Without the trait

Pass a schema (array or fluent Schema) per call — works on plain query builders too:

use Prometa\Lucene\Schema;

DB::table('articles')->whereMatch('title:hobbit', [
    'fields'  => ['title' => 'text'],
    'default' => ['title'],
])->count();

$schema = Schema::make()
    ->text('title', 'body')
    ->exact('status')
    ->number('views')
    ->relation('author', 'author.name')
    ->defaultField('title', 'body')
    ->defaultOperator('or');

Article::query()->whereMatch('title:foo', $schema)->get();

Supported syntax

Field types

Aliasing a field to a differently-named column: 'name' => 'text:full_name'.

Notes & limitations

• Relation fields need an Eloquent builder. whereHas requires Eloquent's relation metadata, so a relation field on a plain DB::table(...) query or via Lucene::toSql() throws UnsupportedFeatureException rather than miscompiling. Use Model::query()->whereMatch(...).
• Date values should be ISO-formatted (2020-01-01). Bounds are parsed with Carbon::parse, which is lenient: a bare year like 2020 is read as a time (today 20:20), and relative words (tomorrow) evaluate against the wall clock. Prefer explicit dates.
• A range on a text field is a lexical comparison (BETWEEN/>=), not a LIKE, and depends on the column collation — usually you want ranges on number/date fields.
• Keep max_depth modest. It guards parser recursion; setting it to many thousands re-opens the risk of a C-stack overflow when PHP destroys a very deeply-nested tree.

Features without a SQL equivalent

Some Lucene features cannot be faithfully expressed in SQL WHERE. Their handling is configurable via lucene.unsupported (throw | ignore | best_effort, default best_effort):

Standalone parser

The Lucene facade exposes the framework-agnostic core for inspection and one-off use:

use Prometa\Lucene\Laravel\Facades\Lucene;

$ast = Lucene::parse('title:foo AND bar~2');              // immutable AST
echo Lucene::explain('a OR (b AND -c)');                  // human-readable tree
['sql' => $sql, 'bindings' => $b] = Lucene::toSql('title:foo', $schema);

Configuration

config/lucene.php:

A model's $lucene['operator'] overrides default_operator for that model.

Security

• Default-deny fields. A field is searchable only if declared in the schema; anything else throws UnknownFieldException. User input never becomes an arbitrary column name.
• Always parameterized. Term/phrase/range/wildcard/regex literals are bound parameters, never concatenated into SQL.
• Explicit ESCAPE. Every LIKE is emitted with an explicit, driver-correct ESCAPE clause, and user-typed %/_ are neutralised before wildcard substitution — so title:50% matches the literal text, not everything.
• Guardrails. max_depth and max_clauses bound the compiled query so a hostile string can't explode it.

Errors

All exceptions extend Prometa\Lucene\Exceptions\LuceneException:

• LuceneParseException — invalid syntax (carries the offset and a caret snippet)
• UnknownFieldException — a field not declared in the schema
• UnsupportedFeatureException — an un-SQL-able feature under a throw policy

A note on precedence

Lucene's classic parser has a famously quirky, non-associative precedence when AND/OR/NOT are mixed without parentheses. This package instead uses a clean, predictable precedence — term modifiers bind tightest, then +/-/NOT, then AND, then OR/juxtaposition — which is what you almost always want for a SQL filter. As in Lucene, use parentheses when you want to be unambiguous.

License

MIT.