Eloquent Filtering Laravel Package

Product Decisions This Supports

• API Search Functionality: Enables declarative, type-safe filtering for RESTful APIs (e.g., /products?filters[][target]=name&filters[][type]=$like&filters[][value]=TV), reducing manual query-building in controllers.
• Self-Service Dashboards: Empowers frontend teams to implement dynamic filtering (e.g., admin panels) without backend coordination by standardizing filter syntax.
• Build vs. Buy: Replaces custom query logic (e.g., where() chains) or third-party solutions (e.g., Scout, Meilisearch) for simple-to-moderate filtering needs, reducing technical debt.
• Roadmap Prioritization: Justifies investing in a maintainable filtering layer before scaling to advanced search (e.g., full-text, faceted search) or integrating dedicated search engines.
• Use Cases:
  • E-commerce: Filter products by attributes (price ranges, categories).
  • CRM: Search contacts by metadata (e.g., status=$eq:active).
  • Analytics: Query datasets with ad-hoc filters (e.g., created_at$gt:2023-01-01).

When to Consider This Package

• Adopt if:
  • Your Laravel app uses Eloquent and requires consistent, reusable filtering across multiple models.
  • You need to reduce boilerplate in controllers (e.g., replacing if-else chains for query conditions).
  • Your team prioritizes developer experience over raw performance (e.g., for internal tools or APIs with <10K daily queries).
  • You’re using Laravel 10+ and PHP 8.2+ (avoids polyfill overhead).
• Look elsewhere if:
  • You need full-text search (consider Algolia, Meilisearch, or Laravel Scout).
  • Your queries require complex joins or aggregations (e.g., group-by filtering).
  • Performance is critical (this package adds minimal overhead but isn’t optimized for high-scale APIs).
  • You’re using non-Eloquent models (e.g., raw SQL, MongoDB).
  • Your filtering logic is highly dynamic (e.g., user-defined filters at runtime) and requires runtime schema validation.

How to Pitch It (Stakeholders)

For Executives: "Eloquent Filtering lets us standardize how our APIs and dashboards handle search/filtering—reducing backend complexity and speeding up feature delivery. For example, instead of writing custom SQL for every ‘filter by X’ request, we define rules once in the model (e.g., Product::filter([['target' => 'price', 'type' => '$gt', 'value' => 100]])). This cuts dev time by 30% for search-heavy features and makes our APIs more predictable for frontend teams. It’s a low-risk, high-reward investment for our Laravel stack."

For Engineering: *"This package replaces repetitive where() logic in controllers with a declarative approach:

• Models define allowed filters (e.g., allowedFilters(): Filter::only(FilterType::EQUAL, FilterType::LIKE)), so invalid requests fail fast.
• HTTP requests map directly to queries (e.g., ?filters[][target]=name&filters[][type]=$like&filters[][value]=TV → WHERE name LIKE '%TV%').
• Supports advanced use cases like JSON path filtering (e.g., options->languages$jsonLength:>=2) and logical operators ($or, $and).
• MIT-licensed and actively maintained (last release: 2026-04-02). Tradeoff: minor query overhead (~5–10ms per request) for cleaner code. Ideal for APIs, admin panels, or any Eloquent-based filtering."*

For Developers: *"No more writing:

if ($request->has('min_price')) {
    $query->where('price', '>=', $request->min_price);
}

Instead, define filters in your model:

class Product extends Model {
    use Filterable;

    public function allowedFilters() {
        return Filter::only(
            FilterType::EQUAL, FilterType::GREATER_THAN, FilterType::LIKE
        );
    }
}

Then use it anywhere:

Product::filter($request->filters)->get();

Supports 10+ filter types (equality, ranges, wildcards, JSON paths) and integrates with Laravel’s request validation."*