daiyanmozumder/laravel-flexsearch

A flexible Laravel search and filter helper for Eloquent models.

v3.0.0 2025-11-06 07:44 UTC

Requires

• php: >=8.0
• illuminate/support: ^10.0|^11.0|^12.0

MIT

• Daiyan Mozumder Milton

README

🔍 Laravel FlexSearch

Powerful Dynamic Filtering, Relationship & Keyword Search for Laravel Eloquent

Created with ❤️ by Daiyan Mozumder

Features • Installation • Quick Start • Documentation • Examples • Contributing

📑 Table of Contents

• ✨ Features
• 📦 Installation
• ⚡ Quick Start
• 🧾 Documentation
• 🧠 How Keyword Search Works
• 🔗 Relationship Filtering & Search
• 💡 Usage Examples
• 🎁 Benefits
• 🤝 Contributing
• 📝 License
• 🔮 Roadmap

✨ Features

🎯 Dynamic Filters	🔍 Keyword Search	🔗 Relationship Aware
Apply simple or operator-based filters (=, >, <, >=, !=) for flexible database queries	Perform powerful full-text-like search across multiple model columns — even in relationships!	Supports filtering and searching through related models using dot notation (e.g. company.name)

🚀 Zero Configuration Required

🎉 No service provider or config needed — works instantly out of the box!

📦 Installation

Install via Composer:

composer require daiyanmozumder/laravel-flexsearch

💡 No additional setup needed! The package is ready to use immediately after installation.

⚡ Quick Start

use DaiyanMozumder\LaravelFlexSearch\FlexSearch;
use App\Models\User;
use Illuminate\Http\Request;

class UserController extends Controller
{
    public function index(Request $request, FlexSearch $flexSearch)
    {
        $query = User::query()->with('company');

        $filters = $request->only(['status', 'company.name']);
        $searchTerm = $request->input('q');
        $searchable = ['name', 'email', 'company.name'];

        $users = $flexSearch->apply($query, $filters, $searchTerm, $searchable)
                            ->paginate(15);

        return view('users.index', compact('users'));
    }
}

✅ That's it! You now have dynamic filters, keyword search, and relational querying in one powerful line.

🧾 Documentation

Method Signature

public function apply(
    Builder $query,
    array $filters = [],
    ?string $searchTerm = null,
    array $searchableColumns = []
): Builder

Parameters

Parameter	Type	Required	Description
$query	Builder	✅	Eloquent query builder instance
$filters	array	❌	Dynamic key-value filters with optional operators
$searchTerm	?string	❌	Keyword(s) for text-based search
$searchableColumns	array	❌	Columns (including relation columns) to search

🧩 Operator-Based Filtering

FlexSearch supports powerful operator-based filtering:

$filters = [
    'price>=' => 100,
    'created_at!=' => '2024-01-01',
    'status' => 'active',
];

Generated SQL:

WHERE price >= 100
  AND created_at != '2024-01-01'
  AND status = 'active'

🔗 Relationship Filtering & Search

You can filter or search within related models using dot notation for seamless relationship querying.

📌 Example 1: Filtering on Relationships

$filters = [
    'company.name=' => 'Ashlar Tech',
    'status' => 'active'
];

$query = User::with('company');
$flexSearch->apply($query, $filters)->get();

Generated SQL (simplified):

WHERE EXISTS (
    SELECT * FROM companies
    WHERE users.company_id = companies.id
      AND companies.name = 'Ashlar Tech'
)
AND users.status = 'active'

🔎 Example 2: Searching on Related Columns

$searchTerm = 'daiyan ashlar';
$searchableColumns = ['name', 'email', 'company.name'];

$query = User::with('company');
$flexSearch->apply($query, [], $searchTerm, $searchableColumns)->get();

Result: Finds users where name, email, or company.name matches any search term.

🧠 How Keyword Search Works

FlexSearch splits your input into words, then applies smart logic:

AND between words → every term must match
OR between columns → each term can match any field

Example:

$searchTerm = "red sport";
$columns = ['title', 'description'];

Generated Query:

WHERE (
    (title LIKE '%red%' OR description LIKE '%red%')
    AND
    (title LIKE '%sport%' OR description LIKE '%sport%')
)

💡 Usage Examples

🛍 Example 1: Product Search

$products = (new FlexSearch())->apply(
    Product::query(),
    ['category_id' => 3, 'price>=' => 100],
    'cotton tshirt',
    ['name', 'description', 'brand.name']
)->get();

👥 Example 2: User Search with Relationships

$query = User::query()->with('company');

$users = (new FlexSearch())->apply(
    $query,
    ['company.name=' => 'Ashlar Tech', 'status' => 'active'],
    'daiyan',
    ['name', 'email', 'company.name']
)->paginate(10);

📰 Example 3: Blog Post Search

$posts = (new FlexSearch())->apply(
    Post::with('author', 'tags'),
    ['category_id' => $request->category],
    $request->search,
    ['title', 'body', 'author.name', 'tags.name']
)->paginate(15);

🎁 Benefits

Feature	Description
🚀 Zero Setup	Works instantly, no config files required
🔧 Highly Flexible	Handles filters, relations, and keywords with ease
⚡ Optimized Queries	Uses whereHas intelligently for better performance
💡 Readable Syntax	Expressive, minimal, and clean API
🧱 ORM Friendly	Seamlessly integrates with Eloquent relationships
🔗 Chainable	Works perfectly with query chains and other builders

🤝 Contributing

We welcome contributions! 🎉

Pull requests are welcome on GitHub.

Guidelines:

• ✅ Follow PSR-12 coding standards
• ✅ Add tests where applicable
• ✅ Keep commits meaningful and scoped
• ✅ Document all new features

🌟 Join our community of contributors!

📝 License

The MIT License (MIT). See LICENSE.md for details.

🙏 Credits

Created & Maintained by
Daiyan Mozumder

Special thanks to all contributors who help make this project better! 🎉

🔮 Roadmap

Status	Feature
✅	Relationship-based search
✅	Operator-based filtering (>, <, >=, !=)
🚧	BETWEEN and IN support
🚧	Fuzzy search and match ranking
📅	Result highlighting
📅	Query caching

💖 Show Your Support

If you find this package helpful, please ⭐ star it on GitHub!

Made with ❤️ by Daiyan Mozumder

Empowering Laravel developers with flexible search solutions