README

A drop-in trait and query builder macro that turns a single search box into rich conditions across selected columns, relations, and casts — with optional Scout integration and relevance ranking.

Why?

Most apps need a "one box" search that just works across names, emails, and related records without hand-writing SQL each time. This package gives you a clean universalSearch() scope plus a whereUniversalSearch() macro you can apply to any Eloquent query.

Features

Single text box -> many columns and relations
Column weights and simple relevance ordering
Fuzzy matching (configurable)
Works with relations via whereHas
Pagination friendly (paginate() as usual)
Optional Laravel Scout adapter (when installed)
Zero-config defaults + per-model config overrides

Installation

composer require jamal/universal-search-filter
php artisan vendor:publish --tag=config --provider="Jamal\\UniversalSearchFilter\\UniversalSearchServiceProvider"

This publishes config/universal_search.php to tweak defaults.

Quick Start

In your Eloquent model:

use Illuminate\Database\Eloquent\Model;
use Jamal\UniversalSearchFilter\Traits\UniversalSearchable;

class User extends Model
{
    use UniversalSearchable;

    // Optional per-model config
    protected array $universalSearch = [
        'columns' => ['name', 'email', 'phone'],
        'relations' => [
            'posts' => ['title', 'body'],
        ],
        'weights' => [
            'name' => 3,
            'email' => 2,
            'posts' => 1, // weight applied to each related column
        ],
        'fuzzy' => true,
        'exclude_zero_relevancy' => true
    ];
}

Then in a controller:

$search = request('q');

$users = User::query()
    ->universalSearch($search) // or ->whereUniversalSearch($search)
    ->paginate(15);

The scope adds a computed _universal_relevance column, and orders by it (higher is better).

What is weight?

Weight is simply a number that shows how important a column (or relation) is compared to others when calculating the relevance score.

Here is how it works:

When you search, the package checks each column you configured (like name, email, phone) to see if the search tokens match.
Each match adds to a computed column called _universal_relevance.
The weight you assign decides how many “points” a match in that column adds.

For example:

protected array $universalSearch = [
        'columns' => [
            'name',
            'email',
            'status'
        ],
        'weights' => [
            'name' => 5,   // highest importance
            'email' => 3,
            'status' => 1, // least important
        ],
];

If you search for "alice":

A hit in the name column adds 5 points.
A hit in the email column adds 3 points.
A hit in the status column adds only 1 point.

The query then orders by _universal_relevance DESC, so results with matches in high-weighted columns appear first.

So weight = ranking priority. It does not remove columns from search, it just decides which matches push a record higher in the list.

Using the Query Builder Macro

If you are on the Query Builder directly (no model) and want a simple multi-column search:

DB::table('users')
    ->whereUniversalSearchOn($search, ['name', 'email', 'phone'])
    ->paginate(20);

Scout (Optional)

If you have Laravel Scout and your model uses the Searchable trait, enable the setting in config/universal_search.php:

'use_scout_when_available' => true,

The scope will route searches via Scout, then hydrate your Eloquent query based on the keys returned. If no results are found, it falls back to the Eloquent driver.

Configuration

config/universal_search.php:

columns: default columns when a model does not provide its own list
relations: relation => [columns] pairs
weights: increase importance of certain columns/relations
fuzzy: true uses %token%, false uses prefix token%
min_token_length: ignore very short tokens
use_scout_when_available: prefer Scout when the model is searchable

Notes on Relevance

The package builds a simple relevance score with a CASE WHEN column LIKE ? THEN weight sum across tokens and columns. This is portable and works on MySQL, Postgres, and SQLite. For advanced ranking, consider switching to Scout with a dedicated engine (e.g., Meilisearch, Algolia, TNTSearch).

Examples

Search users by "john doe" across users and their posts:

$users = User::universalSearch('"john doe"')
    ->with('posts')
    ->paginate();

Provide options at call site:

$users = User::universalSearch($search, [
    'fuzzy' => false, // switch to prefix matching
    'min_token_length' => 3,
]);

Use only the macro with manual columns:

$orders = Order::query()
    ->whereUniversalSearch($search, ['columns' => ['reference', 'status']])
    ->paginate();

Testing (stub)

You can write tests by making a few models with the trait and seeding a handful of rows, then asserting counts and order of _universal_relevance.

License

MIT

Tailored Defaults

Out of the box, the config ships with useful defaults:

columns: name, email, title, phone, reference, status
weights: name (5), email (4), title/reference (3), status (1)
Empty relations so you can opt-in per model

Override at the model level by defining $universalSearch or globally by publishing the config.

Running Tests

This package uses PHPUnit with Orchestra Testbench.

composer install
composer test

The test suite provisions an in-memory SQLite database, runs simple migrations, seeds demo data, then verifies:

token parsing for quoted phrases
column and relation search results
relevance column is appended and used for ordering
macro usage on the plain query builder
fuzzy vs prefix matching

jamal / universal-search-filter

Maintainers

Details