Laravel SmartSearch

Laravel search package — the most versatile full text search for Laravel with OpenSearch, Elasticsearch, Scout, and database search.
Zero-config, production-safe, queue-driven search indexing with AI-powered semantic & vector search.
A powerful Eloquent search engine for your models.

What is Laravel SmartSearch?

Laravel SmartSearch is a powerful, production-ready Laravel search package that provides a unified search API across OpenSearch, Elasticsearch, Laravel Scout, and database full-text search — a true Laravel Scout alternative with more flexibility. Built by Fatehi AL-AGHBARI, it solves the common pain points teams face when adding search to Laravel applications — complex setup, vendor lock-in, and brittle fallback logic.

Whether you need OpenSearch for Laravel, Elasticsearch for Laravel, a Laravel Scout alternative, or database search for Laravel, SmartSearch gives you one clean Laravel search API that works everywhere. The Eloquent search layer integrates directly with your models for zero-friction indexing.

Why Laravel SmartSearch?

Integrating search for Laravel applications often means:

• Hard-coding Elasticsearch queries
• Breaking changes when switching providers
• No safety net when the search engine goes down
• Painful multilingual setup (especially Arabic)

SmartSearch fixes all of this:

Features

• Unified Laravel search API — SmartSearch::for(Model::class)->query('term')->get()
• Full text search for Laravel — works out of the box with database search, no extra packages
• Eloquent search — trait-based, integrates directly with your models
• Database search Laravel — LIKE / ILIKE auto-detects MySQL, PostgreSQL, SQLite, SQL Server
• Elasticsearch for Laravel — high-performance dedicated search, install only if needed
• OpenSearch for Laravel — open-source search engine, fully compatible API
• Laravel Scout bridge — works with Algolia, MeiliSearch, Typesense through Scout
• Search indexing — queue-driven on model created/updated/deleted
• Automatic safe fallback — if Elasticsearch/Scout is down, falls back to database
• Arabic search for Laravel — built-in normalization for Arabic content
• Multilingual search — configurable analyzers for any language
• Driver-based architecture — Strategy Pattern, extensible
• Works with any database — MySQL, PostgreSQL, SQLite, SQL Server, no breaking changes
• Laravel 9 / 10 / 11 / 12 / 13 — full backward compatibility

What Sets SmartSearch Apart

These features are not available in Elasticsearch or Laravel Scout alone. They are the unique value SmartSearch brings:

SmartSearch is not "yet another wrapper." It is an open-source abstraction layer that:

• Unifies database, OpenSearch, Elasticsearch, and Scout providers under one fluent API
• Adds features no single engine provides alone (PHP-level Arabic normalization, driver fallback, queue-by-default indexing)
• Gives OpenSearch and Elasticsearch first-class support — no community adapters needed
• Lets you start with the free database driver, migrate to self-hosted OpenSearch, then scale to Elasticsearch or Scout providers — all by changing one .env line

Driver Architecture

SmartSearch decouples your application from the search engine. The architecture has three layers — your code, the manager, and the drivers:

Layer 1 — Your Code (unified API, never changes)

Layer 2 — SearchManager (routes to the active driver)

Layer 3 — Drivers (execution engines)

ScoutDriver providers:

Installation

Core package

This installs the core package with the database driver only — no extra dependencies, no conflicts.

Optional driver packages

The database driver works immediately. For other search engines, install the corresponding package:

The package auto-detects which drivers are installed — missing packages just mean that driver throws a clear error message if used.

Publish config (optional)

Quick Setup

1. Add the trait to your model

2. (Optional) Configure your driver

The default driver is database — works immediately with your existing database. To switch to Elasticsearch:

That's it.

Elasticsearch Setup

To use the Elasticsearch for Laravel driver, set the driver in your .env:

Connecting to Elasticsearch

Local / self-hosted:

With Basic Auth:

With API Key (takes precedence over Basic Auth):

Where to get an API key: https://cloud.elastic.co > Your deployment > Stack Management > Security > API Keys > Create API key

Elastic Cloud:

No port or host needed — Cloud ID resolves endpoints automatically.

Where to get Cloud ID: https://cloud.elastic.co > Your deployment > Copy Cloud ID (or Help icon > Connection Details)

Additional Options

Note: The Elasticsearch driver requires a separate install: composer require elasticsearch/elasticsearch. The package detects its presence automatically.

OpenSearch Setup

To use the OpenSearch for Laravel driver, first install the client:

Then set the driver in your .env:

Connecting to OpenSearch

OpenSearch uses the same HTTP API as Elasticsearch. The driver requires opensearch-project/opensearch-php but the setup is almost identical:

Local / self-hosted:

With API Key:

Docker (OpenSearch official image):

Note: OpenSearch is the open-source fork of Elasticsearch — fully compatible API, Apache 2.0 license, no Elastic Cloud dependency. Perfect for self-hosted production search without licensing costs.

Additional Options

Semantic Search (AI-Powered Embeddings & Vector Search)

AI-powered semantic search — a game-changer for the search world.
SmartSearch understands meaning, not just keywords. Powered by free, local Ollama — no subscriptions, no third-party APIs.
Perfect for SEO, user experience, and Arabic & multilingual applications.

SmartSearch supports semantic search using vector embeddings — it understands meaning, not just keywords. This is powered by Ollama (free, local, no API keys).

How it works

1. Install and run Ollama

Docker:

2. Add embedding column to your model's table

3. Configure which fields to embed (optional)

Override searchableEmbeddings() on your model — defaults to the same fields as $smartSearchable:

4. Enable auto-indexing

Set SMARTSEARCH_EMBEDDINGS_ENABLED=true in your .env. The package will generate embeddings for your models automatically on save (via queue jobs).

5. Search semantically

The similarTo() method accepts an optional weight parameter that controls the balance between full-text and semantic results:

Driver compatibility

Zero-cost semantic search: With database driver + Ollama locally, you get AI-powered search for $0 — no API fees, no external services.

Scout Driver

To use the Scout driver, you first install and configure Laravel Scout normally — it has its own .env variables and config/scout.php settings independent of SmartSearch:

Since Scout manages its own model events, use Scout's own Searchable trait on your model (not SmartSearch's):

SmartSearch's ScoutDriver will call Scout's API through your model. Auto-indexing is handled by Scout internally.

Scout is optional (require-dev). Run composer require laravel/scout and publish its config to use it.

Environment Variables

Usage

Basic search

Search with filters

Paginated search

Eloquent-style shortcut

Helper function

Auto Indexing

SmartSearch hooks into Eloquent events to keep your search index in sync automatically:

All operations are queue-based (non-blocking) and configurable.

Safe Database Fallback

When your primary search engine (Elasticsearch / Scout) is unavailable:

The database driver auto-detects your database engine:

Arabic & Multilingual Search

Full Arabic search for Laravel and multilingual search support out of the box:

Configurable Elasticsearch analyzer for any language:

Driver System

Configuration

Architecture

Built on clean architecture principles:

• Strategy Pattern for drivers
• Service Container binding
• Event-driven indexing
• SOLID principles throughout

Use Cases

• E-commerce search — product search with filters and faceting
• ERP systems — search across invoices, customers, orders
• SaaS platforms — multi-tenant search (coming soon)
• Real estate listings — full-text property search
• Document management — search titles, descriptions, content
• Arabic content platforms — normalized Arabic search for Laravel

Requirements

• PHP 8.1+
• Laravel 9.x / 10.x / 11.x / 12.x / 13.x
• Database MySQL / PostgreSQL / SQLite / SQL Server (any Laravel-supported database)
• Elasticsearch 7.x+ (only if using the Elasticsearch driver — optional)

Contributing

1. Fork the repo
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push (git push origin feature/my-feature)
5. Open a Pull Request

Support

If this Laravel search package helps you:

• Star the repository on GitHub
• Report issues
• Share with the Laravel community
• Looking for an Elasticsearch Laravel or database search solution? This is it.

License

MIT License. Free for personal and commercial use.