Download the PHP package illuma-law/laravel-hybrid-search without Composer

Laravel Hybrid Search

Portable Full-Text Search macros and Reciprocal Rank Fusion for Laravel.

This package provides portable Full-Text Search (FTS) schema macros and the Reciprocal Rank Fusion (RRF) algorithm for Laravel applications. It enables seamless text searching across PostgreSQL, MySQL, SQL Server, and SQLite, abstracting away the database-specific syntax. It also provides an elegant way to merge and re-rank traditional keyword search results with AI vector search results.

Features

• Database Portability: Write one migration and one query that works across all supported databases.
• SQLite FTS5 Support: Automatically creates Virtual Tables and database triggers to keep SQLite full-text indexes synchronized.
• Reciprocal Rank Fusion: Mathematically combine multiple ranked lists (e.g., BM25 + Vector Similarity) into a single optimized result set.
• Scout Key Trait: Ensure Scout-indexed models always return a string primary key — required for Typesense and other engines that reject integer keys.
• Scout Health Check: Optional spatie/laravel-health check that probes Meilisearch, Typesense, and Algolia endpoints.

Database Support Matrix

*SQL Server requires manual creation of the Full-Text Catalog.

Installation

You can install the package via composer:

The service provider will automatically register the Blueprint and Builder macros.

Usage & Integration

Schema Migrations

Use the hybridFullText macro in your migrations.

On PostgreSQL and MySQL, this directly uses Laravel's native full-text index generation. On SQLite, it creates an FTS5 virtual table (e.g., articles_fts) and sets up INSERT, UPDATE, and DELETE database triggers. This ensures your SQLite virtual table automatically stays synchronized with your main table without requiring any PHP-side application logic.

Full-Text Searching

Use the whereHybridFullText macro on any Query Builder or Eloquent Builder. It automatically handles the complex MATCH syntax for SQLite FTS5 and the CONTAINS syntax for SQL Server, while using native whereFullText on PostgreSQL and MySQL.

You can also invert the search to exclude matches:

Reciprocal Rank Fusion (RRF)

When building advanced search systems, you often want to retrieve the top results using traditional keyword search (BM25) and semantic vector search (Cosine Similarity), then combine them.

The ReciprocalRankFusion class merges these disparate result sets by assigning an RRF score to each item based on its position in the original ranked lists.

Scout Key Trait

Some search engines (e.g. Typesense) require Scout keys to be strings. Add the EnsuresScoutKeyIsString trait to any model that uses integer or UUID primary keys alongside the Scout Searchable trait.

Scout Health Check

An optional spatie/laravel-health check that pings the configured Scout engine's health endpoint. Supports Meilisearch, Typesense, and Algolia. Non-remote drivers (database, collection, null) are automatically skipped.

Install the optional dependency first:

Then register the check in your application:

The check reads standard Scout configuration keys (scout.driver, scout.meilisearch.*, scout.typesense.*, scout.algolia.*). You can adjust the request timeout via config('health.scout.timeout_seconds') (default: 5).

Testing

Run the test suite:

License

The MIT License (MIT). Please see License File for more information.