PHPackages                             aghfatehi/laravel-smartsearch - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. aghfatehi/laravel-smartsearch

ActiveLibrary[Database & ORM](/categories/database)

aghfatehi/laravel-smartsearch
=============================

Laravel SmartSearch by Fatehi AL-AGHBARI — production-grade search abstraction layer for Laravel with OpenSearch, Elasticsearch, Scout, and database fallback. Unified search API, automatic indexing, Arabic/multilingual support, queue-driven, safe fallback. AI-powered semantic search with vector embeddings. The most flexible Laravel search package for Eloquent models.

v1.4.0(2d ago)016↑2712.5%MITPHPPHP ^8.1CI passing

Since Jun 7Pushed 2d agoCompare

[ Source](https://github.com/aghfatehi/laravel-smartsearch)[ Packagist](https://packagist.org/packages/aghfatehi/laravel-smartsearch)[ RSS](/packages/aghfatehi-laravel-smartsearch/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (3)Dependencies (9)Versions (6)Used By (0)

 [![PHP Version](https://camo.githubusercontent.com/d4fe5599dc4fb02fe432b94f8a25d1b06cfc6fbaad6f0baa6dc87ee043ca3e98/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d5e382e312d3838393242462e7376673f7374796c653d666f722d7468652d6261646765266c6f676f3d706870)](https://www.php.net/) [![Laravel Version](https://camo.githubusercontent.com/b7659162668560f1d9c9b9f097fe5f0f26b317a9b789c2908148eadc43f15cf5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d397c31307c31317c31327c31332d4646324432302e7376673f7374796c653d666f722d7468652d6261646765266c6f676f3d6c61726176656c)](https://laravel.com/) [![Drivers](https://camo.githubusercontent.com/85f8222411a2b26c7c11547743ef1ac9fe2b219e1340886f0df117454e506be5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f447269766572732d4f70656e5365617263685f2532425f456c61737469637365617263685f2532425f53636f75745f2532425f44617461626173652d3030413835392e7376673f7374796c653d666f722d7468652d6261646765)](#driver-system) [![AI Search](https://camo.githubusercontent.com/ab4ffc543f0828f62caad9a64d7553fa95a0af1f066b759ede6369dc5430e82e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f41495f5365617263682d566563746f725f2532425f53656d616e7469632d4646364630302e7376673f7374796c653d666f722d7468652d6261646765)](#semantic-search-ai-powered-embeddings--vector-search) [![License](https://camo.githubusercontent.com/31e62e0eff03ce9ddfdf69d8476340d4f541990bfb152cb02a0f342965252997/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e7376673f7374796c653d666f722d7468652d6261646765)](LICENSE) [![Tests](https://camo.githubusercontent.com/d43c60ead7e53cac5a535d1a83256d613ce0f5f934a24332a7d7ba8364605d13/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6167686661746568692f6c61726176656c2d736d6172747365617263682f74657374732e796d6c3f7374796c653d666f722d7468652d6261646765266c6162656c3d5465737473266272616e63683d6d61696e)](https://github.com/aghfatehi/laravel-smartsearch/actions) [![Packagist](https://camo.githubusercontent.com/e084959a629fa8da35b431c1ea195f91ce8c34a5fa330cb30a68ae6c835fc62c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6167686661746568692f6c61726176656c2d736d6172747365617263682e7376673f7374796c653d666f722d7468652d6261646765)](https://packagist.org/packages/aghfatehi/laravel-smartsearch) [![Downloads](https://camo.githubusercontent.com/4eb13db192178ef739f65c86ec7b643020b632a59b2efb4394becc926153f354/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6167686661746568692f6c61726176656c2d736d6172747365617263682e7376673f7374796c653d666f722d7468652d6261646765)](https://packagist.org/packages/aghfatehi/laravel-smartsearch) [![FsoftDev](https://camo.githubusercontent.com/d6dcdc51ab1d6a32843c2936f8b0b38bdc58aba5634c2ef96e451791ca293210/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f46736f66744465762d46736f66744465762e636f6d2d626c75652e7376673f7374796c653d666f722d7468652d6261646765)](https://fsoftdev.com) [![Author](https://camo.githubusercontent.com/369b3da733224d2abc71724d11cef62b04f53ad2dcd876721f32e0d989da39d3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f417574686f722d414c2d2d414748424152492532304661746568692d626c75652e7376673f7374796c653d666f722d7468652d6261646765)](https://github.com/aghfatehi)

Laravel SmartSearch
===================

[](#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?
----------------------------

[](#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?
------------------------

[](#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:**

ProblemTraditional ApproachSmartSearchSetup complexityHours of config1-minute setupVendor lock-inTied to one engineSwitch drivers anytimeNo fallback503 errorsAuto database fallbackArabic searchCustom hacksBuilt-in normalizerIndexing overheadManual syncAuto queue-driven---

Features
--------

[](#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
---------------------------

[](#what-sets-smartsearch-apart)

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

FeatureElasticsearch NativeOpenSearch NativeLaravel Scout NativeSmartSearch**Single API across engines**NoNoNo — Scout providers onlyYes — database, OpenSearch, Elasticsearch, **and** Scout through one API**Standalone DB driver**NoNoRequires Scout ecosystemYes — works standalone, no extra packages**Queue auto-indexing**No — you build itNo — you build itOpt-in (`SCOUT_QUEUE=true`)Yes — **enabled by default**, zero config**Automatic fallback**No — downtime = 503No — downtime = 503No — only pagination count fallbackYes — configurable fallback driver**Arabic normalization**Server-side onlyServer-side onlyNoYes — PHP-level across **all** drivers**OpenSearch support**NoN/A (is OpenSearch)Requires community driverYes — built-in driver, no extra config**Elasticsearch support**N/A (is Elasticsearch)NoRequires community driverYes — built-in driverSmartSearch 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
-------------------

[](#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-1--your-code-unified-api-never-changes)

```
SmartSearch::for(Product::class)->query('phone')->where('price', '>', 100)->get();
```

### Layer 2 — SearchManager (routes to the active driver)

[](#layer-2--searchmanager-routes-to-the-active-driver)

SettingValue`SMARTSEARCH_DRIVER`Pick one: `database`, `opensearch`, `elasticsearch`, `scout``SMARTSEARCH_FALLBACK`Optional fallback if primary driver fails### Layer 3 — Drivers (execution engines)

[](#layer-3--drivers-execution-engines)

DriverTypeMechanismCostSetup Effort`DatabaseDriver`Standalone`LIKE` / `ILIKE` auto-detectFreeNone — works immediately`OpenSearchDriver`StandaloneHTTP API via `opensearch-php`FreeMedium — Docker self-hosted`ElasticsearchDriver`StandaloneHTTP API via `elasticsearch-php`Cloud / Self-hostedMedium — Cloud ID or hosts`ScoutDriver`BridgeDelegates to Scout providersPer providerLow — Scout + API keysScoutDriver providers:

ProviderTypeEnvironmentAlgoliaPaid cloudSaaS, zero server managementMeiliSearchFree open-source / Paid cloudSelf-hosted or managed cloudTypesenseFree open-source / Paid cloudSelf-hosted or managed cloud---

Installation
------------

[](#installation)

### Core package

[](#core-package)

```
composer require aghfatehi/laravel-smartsearch
```

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

### Optional driver packages

[](#optional-driver-packages)

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

EngineCommandRequired for**Elasticsearch**`composer require elasticsearch/elasticsearch``SMARTSEARCH_DRIVER=elasticsearch`**OpenSearch**`composer require opensearch-project/opensearch-php``SMARTSEARCH_DRIVER=opensearch`**Scout** (Algolia / MeiliSearch / Typesense)`composer require laravel/scout``SMARTSEARCH_DRIVER=scout`The package auto-detects which drivers are installed — missing packages just mean that driver throws a clear error message if used.

### Publish config (optional)

[](#publish-config-optional)

```
php artisan vendor:publish --tag=smartsearch-config
```

---

Quick Setup
-----------

[](#quick-setup)

### 1. Add the trait to your model

[](#1-add-the-trait-to-your-model)

```
use SmartSearch\Traits\SmartSearchable;

class Product extends Model
{
    use SmartSearchable;

    protected $smartSearchable = ['name', 'description', 'price'];
}
```

### 2. (Optional) Configure your driver

[](#2-optional-configure-your-driver)

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

```
SMARTSEARCH_DRIVER=elasticsearch
SMARTSEARCH_FALLBACK=database
```

That's it.

Elasticsearch Setup
-------------------

[](#elasticsearch-setup)

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

```
SMARTSEARCH_DRIVER=elasticsearch
```

### Connecting to Elasticsearch

[](#connecting-to-elasticsearch)

**Local / self-hosted:**

```
ELASTICSEARCH_HOSTS=localhost:9200
```

**With Basic Auth:**

```
ELASTICSEARCH_HOSTS=localhost:9200
ELASTICSEARCH_USER=elastic
ELASTICSEARCH_PASS=changeme
```

**With API Key (takes precedence over Basic Auth):**

```
ELASTICSEARCH_HOSTS=localhost:9200
ELASTICSEARCH_API_KEY=base64encodedapikey
```

> Where to get an API key:  > Your deployment > Stack Management > Security > API Keys > Create API key

**Elastic Cloud:**

```
SMARTSEARCH_DRIVER=elasticsearch
ELASTICSEARCH_CLOUD_ID=my-cluster:dXM...
ELASTICSEARCH_USER=elastic
ELASTICSEARCH_PASS=yourpassword
```

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

> Where to get Cloud ID:  > Your deployment > Copy Cloud ID (or Help icon > Connection Details)

### Additional Options

[](#additional-options)

```
ELASTICSEARCH_RETRIES=3          # Connection retries on failure
ELASTICSEARCH_SSL_VERIFY=true    # SSL cert verification
ELASTICSEARCH_ANALYZER=arabic    # Text analyzer (standard, arabic, english, etc.)
```

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

---

OpenSearch Setup
----------------

[](#opensearch-setup)

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

```
composer require opensearch-project/opensearch-php
```

Then set the driver in your `.env`:

```
SMARTSEARCH_DRIVER=opensearch
SMARTSEARCH_FALLBACK=database
```

### Connecting to OpenSearch

[](#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:**

```
OPENSEARCH_HOSTS=https://localhost:9200
OPENSEARCH_USER=admin
OPENSEARCH_PASS=admin
OPENSEARCH_SSL_VERIFY=false    # Self-signed certs in dev
```

**With API Key:**

```
OPENSEARCH_HOSTS=https://opensearch-cluster:9200
OPENSEARCH_API_KEY=base64encodedapikey
```

**Docker (OpenSearch official image):**

```
# docker-compose.yml
services:
  opensearch:
    image: opensearchproject/opensearch:latest
    environment:
      - discovery.type=single-node
      - plugins.security.disabled=true    # Disable security for dev
    ports:
      - "9200:9200"
```

> **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

[](#additional-options-1)

```
OPENSEARCH_RETRIES=3          # Connection retries on failure
OPENSEARCH_SSL_VERIFY=true    # SSL cert verification
OPENSEARCH_ANALYZER=arabic    # Text analyzer (standard, arabic, english, etc.)
```

---

Semantic Search (AI-Powered Embeddings & Vector Search)
-----------------------------------------------------------

[](#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](https://ollama.com) — 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](https://ollama.com) (free, local, no API keys).

### How it works

[](#how-it-works)

```
SMARTSEARCH_EMBEDDINGS_ENABLED=true
SMARTSEARCH_EMBEDDINGS_PROVIDER=ollama
SMARTSEARCH_EMBEDDINGS_MODEL=nomic-embed-text
SMARTSEARCH_EMBEDDINGS_HOST=http://localhost:11434

```

SettingDefaultDescription`SMARTSEARCH_EMBEDDINGS_ENABLED``false`Set to `true` to enable semantic search`SMARTSEARCH_EMBEDDINGS_PROVIDER``ollama`Embedding provider (only `ollama` currently)`SMARTSEARCH_EMBEDDINGS_MODEL``nomic-embed-text`Model — see [ollama embeddings](https://ollama.com/search?c=embedding)`SMARTSEARCH_EMBEDDINGS_HOST``http://localhost:11434`Ollama server URL (Docker: `http://ollama:11434`)`SMARTSEARCH_EMBEDDINGS_DIMENSIONS`autoVector dimensions (768 for nomic-embed-text)`SMARTSEARCH_EMBEDDINGS_TIMEOUT``30`Request timeout in seconds### 1. Install and run Ollama

[](#1-install-and-run-ollama)

```
# Install Ollama: https://ollama.com

# Pull an embedding model
ollama pull nomic-embed-text

# Run the server (starts automatically on install)
ollama serve
```

Docker:

```
services:
  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
```

```
docker compose exec ollama ollama pull nomic-embed-text
```

### 2. Add embedding column to your model's table

[](#2-add-embedding-column-to-your-models-table)

```
Schema::table('products', function ($table) {
    $table->text('embedding')->nullable();
});
```

### 3. Configure which fields to embed (optional)

[](#3-configure-which-fields-to-embed-optional)

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

```