Laravel Cross Eloquent Search

This package provides a unified way to search through multiple Eloquent models simultaneously. Key capabilities include:

• Multi-model Search: Search through one or more Eloquent models.
• Pagination: Supports cross-model pagination.
• Column Flexibility: Search through single or multiple columns, including nested relationships.
• Full-Text Search: Supports Full-Text Search across models and relationships. The package automatically selects the correct strategy based on your database (MySQL native indexes, PostgreSQL tsquery with pg_trgm, or SQLite LIKE).
• Sorting & Ordering: Order results by cross-model columns or by relevance.
• Query Customization: Use Eloquent constraints, scoped queries, and eager load relationships for each model.
• Database Support: Works with MySQL, PostgreSQL, and SQLite with zero third-party dependencies.

By default, search results do not include the model type. To include it, call includeModelType(). This adds a type key to the result data.

• Customizing the key: Pass a string to includeModelType('my_key') to change the key name.
• Customizing the value: To change the value returned (e.g., from Post to article), add a public function searchType() method to your Eloquent model.

// In your Model
class Video extends Model
{
    public function searchType()
    {
        return 'awesome_video';
    }
}

// In your Search
Search::add(Post::class, 'title')
    ->includeModelType()
    ->search('foo');

By default, the package splits search terms and appends a % wildcard to each keyword for partial matching (e.g., apple becomes apple%).

• beginWithWildcard(): Adds a wildcard to the start of terms (e.g., %apple%).
• endWithWildcard(bool $value): Controls whether a wildcard is appended to the end. Call endWithWildcard(false) to disable trailing wildcards.
• exactMatch(): Disables all wildcards and uses the = operator instead of LIKE for strict equality.

// Partial matching with both sides
Search::add(Post::class, 'title')
    ->beginWithWildcard()
    ->search('os');

// Exact matching
Search::add(Post::class, 'title')
    ->exactMatch()
    ->search('Laravel');

You can use Search::new() to start a fresh instance, which is useful for method chaining and indentation.

• Use when($condition, $callback) to conditionally add models to the searcher.
• Use tap($callback) to access the searcher instance (e.g., for logging configuration) before executing the search.
• Use includeModelType($customKey = 'type') to add a field to the results identifying the model type.

// Conditional adding
Search::new()
    ->when($user->isVerified(), fn($search) => $search->add(Post::class, 'title'))
    ->when($user->isAdmin(), fn($search) => $search->add(Video::class, 'title'))
    ->search('howto');

// Tapping into the instance
Search::add(Post::class, 'title')
    ->tap(function ($searcher) {
        Log::info('Search configuration', ['models' => $searcher->getModelsToSearchThrough()]);
    })
    ->search('laravel');

Ensure your environment meets the following minimum requirements:

• PHP: 8.2 or higher
• Laravel: 11.0+
• Databases:
  • MySQL 8.0+
  • PostgreSQL 12+
  • SQLite 3.8+

To search across multiple Eloquent models, use the Search::add() method to specify the model class and the column to search. Finally, call search() with your query term. This returns an ext{Illuminate extbackslash Database extbackslash Eloquent extbackslash Collection} of results.

By default, results are sorted in ascending order by the model's updated_at column (or the primary key if timestamps are not used).

use ProtoneMedia\
LaravelCrossEloquentSearch\\Search;

$results = Search::add(Post::class, 'title')
    ->add(Video::class, 'title')
    ->search('howto');

If you are upgrading from version 2 to version 3, note the following breaking changes:

• Method Rename: The get method is now search.
• Method Removal: The addWhen method has been removed. Use the when method instead.
• Default Sorting: Results are now sorted by the updated column by default (typically updated_at). If your models do not use timestamps, it will default to the primary key.

Install the package using Composer to enable searching across multiple Eloquent models with support for pagination, sorting, and relationships.

composer require protonemedia/laravel-cross-eloquent-search

If you are upgrading from version 1 to version 2, note the following breaking changes:

• Method Rename: The startWithWildcard method is now beginWithWildcard.
• Order Column Logic: The default order column is now determined by the getUpdatedAtColumn method, rather than being hard-coded to updated_at.
• Empty Search Handling: The allowEmptySearchQuery method and EmptySearchQueryException class have been removed. To get results without a search query, follow the getting results without searching pattern.

To avoid loading massive result sets, use pagination. The returned object will be an instance of Laravel's paginator.

• paginate($perPage, $pageName, $page): Standard length-aware pagination.
• simplePaginate($perPage, $pageName, $page): Simple pagination (no total count).
• withQueryString($parameters = null): Retains query string parameters in pagination links. If $parameters is provided, it uses those specific keys; otherwise, it uses the current request's query string.

// Standard pagination with query string retention
Search::add(Post::class, 'title')
    ->paginate(15)
    ->withQueryString()
    ->search('build');

// Simple pagination
Search::add(Post::class, 'title')
    ->simplePaginate(15)
    ->search('build');