Laravel Eloquent Filter Laravel Package

Technical Evaluation

Architecture Fit

• Pros:
  • Eloquent-Centric: Seamlessly integrates with Laravel’s Eloquent ORM, reducing friction for teams already using it. Aligns with Laravel’s query builder patterns, minimizing learning curves.
  • Declarative Filtering: Encourages separation of concerns by moving filter logic out of controllers into dedicated Filter classes, improving maintainability.
  • Lightweight: Minimal abstraction overhead; leverages native Laravel features (e.g., validation, request handling) without introducing heavy dependencies.
  • MIT License: No legal or licensing constraints, enabling easy adoption and modification.
• Cons:
  • Eloquent Dependency: Tight coupling to Eloquent limits flexibility for projects using raw Query Builder, non-Laravel ORMs, or alternative data access layers.
  • Stagnant Maintenance: Last updated in 2021, with no signs of active development. Risks include compatibility issues with Laravel 8.x+ features (e.g., stricter type hints, query builder improvements).
  • Limited Feature Set: Lacks advanced capabilities like nested filters, real-time validation, or support for Laravel’s newer query methods (e.g., whereJsonContains, whereBetween with nullable values).
  • No Built-in Caching: Dynamic filter compilation could lead to performance bottlenecks in high-traffic scenarios without additional caching layers.

Integration Feasibility

• Low-Risk for Greenfield Projects:
  • Minimal setup (installation, service provider registration, basic configuration) with clear, if sparse, documentation.
  • Ideal for projects starting from scratch or those with homogeneous Eloquent-based architectures.
• High-Risk for Legacy Systems:
  • Potential conflicts with existing query-scoping mechanisms (e.g., global scopes, model observers, or custom query macros).
  • May require refactoring of legacy where() clauses in controllers or repositories.
  • No support for Laravel 9/10’s query builder enhancements (e.g., whereJsonLength, orWhereDoesntHave).
• Testing Requirements:
  • Unit tests exist but are minimal; integration tests for edge cases (e.g., SQL injection attempts, malformed inputs) are untested.
  • Requires manual validation of filter logic against business requirements (e.g., multi-tenancy, soft deletes).

Technical Risk

• Deprecation Risk:
  • Laravel’s core query builder evolves rapidly (e.g., PHP 8.1+ type safety, Laravel 9’s query builder changes). This package remains static, increasing the likelihood of compatibility issues.
  • Example: Laravel 8.79+ introduced stricter type hints for query builders, which this package does not account for.
• Performance Risks:
  • Dynamic filter compilation could introduce overhead, especially for complex queries (e.g., nested whereHas or orWhere conditions).
  • No benchmarks or guidance on optimizing filter performance (e.g., indexing strategies, caching frequent filters).
• Security Risks:
  • Input Validation: Relies entirely on Laravel’s validation layer. Malicious or malformed inputs (e.g., SQL injection via dynamic column names) are not handled by the package itself.
  • N+1 Queries: Filters applied without eager loading (with()) can trigger N+1 query issues, especially in nested relationships.
• Functional Gaps:
  • No support for:
    • Multi-tenancy (e.g., filtering by tenant ID in a shared database).
    • Soft-deleted models (e.g., withTrashed() integration).
    • JSON fields (e.g., filtering nested JSON attributes).
    • Real-time updates (e.g., WebSocket-driven filters).

Key Questions

1. Compatibility:
   • What version of Laravel is the project using? If Laravel 9/10, how will this package be adapted (e.g., polyfills, forks)?
   • Are there existing query-scoping mechanisms (e.g., global scopes, model observers) that could conflict with this package?
   • Does the project use raw Query Builder or non-Eloquent ORMs? If so, is this package a viable solution?
2. Functional Requirements:
   • Are advanced filter types required (e.g., multi-tenancy, soft deletes, JSON fields)? If yes, how will these be implemented?
   • How will filters integrate with API versioning or feature flags (e.g., enabling filters for specific API endpoints)?
   • Are there performance requirements (e.g., sub-100ms response times) that could be impacted by dynamic filter compilation?
3. Maintenance and Longevity:
   • Who will be responsible for maintaining or forking this package if Laravel breaks backward compatibility?
   • Are there plans to migrate to a more actively maintained alternative (e.g., spatie/laravel-query-builder) in the long term?
   • How will the team handle security updates or vulnerabilities in Laravel’s query builder (which this package depends on)?
4. Alternatives:
   • Would a custom query builder trait or a more feature-rich package (e.g., spatie/laravel-query-builder, beberlei/DoctrineExtensions) better meet the project’s needs?
   • Are there internal libraries or patterns already in use that could replace this package?
5. Operational Impact:
   • How will filter logic be tested (e.g., unit tests, integration tests, manual QA)?
   • What monitoring or logging will be implemented to track filter performance and failures?
   • How will the team handle debugging of filter-related issues (e.g., opaque query generation)?

Integration Approach

Stack Fit

• Ideal Use Cases:
  • APIs with Simple CRUD Filtering: Perfect for RESTful endpoints where clients need to filter resources (e.g., /users?status=active&role=admin).
  • Admin Panels: Streamlines the implementation of search/filter functionality in Laravel Nova or custom admin interfaces.
  • SaaS Platforms: Enables role-based or tenant-specific filtering with minimal boilerplate.
  • Reporting Tools: Accelerates the development of dynamic query interfaces for internal dashboards.
• Poor Fit:
  • Projects Using Raw Query Builder: Tight coupling to Eloquent makes this package unsuitable for projects relying on raw SQL or non-Laravel ORMs.
  • Complex Aggregations: Lacks support for nested filters, full-text search, or advanced aggregations (e.g., groupBy with conditions).
  • Real-Time Systems: Not designed for WebSocket-driven or real-time filtering (e.g., live search-as-you-type).
  • Laravel 9/10 Projects: Requires manual adjustments or forking to maintain compatibility with newer Laravel features.

Migration Path

1. Assessment Phase:
   • Audit Existing Queries: Identify all manual where() clauses in controllers, repositories, or services that could be replaced by filters.
   • Compatibility Check: Verify that the package works with the project’s Laravel version and existing query-scoping mechanisms (e.g., global scopes, observers).
   • Test Environment Setup: Isolate a non-critical endpoint (e.g., a staging API) for pilot testing.
2. Implementation:
   • Phase 1: Pilot Endpoint:
     • Replace manual queries with Filter classes for 1–2 endpoints (e.g., a user search or product listing).
     • Validate functionality with test cases covering:
       • Basic filtering (e.g., status=active).
       • Edge cases (e.g., empty inputs, invalid values).
       • Performance under load.
   • Phase 2: Controller Refactoring:
     • Centralize filter logic into dedicated Filter classes (e.g., UserFilter, OrderFilter).
     • Replace where() clauses in controllers with Filter::apply() or query()->filter().
     • Example:

       // Before
       $users = User::where('status', $request->status)
                    ->where('created_at', '>', $request->date)
                    ->get();
       
       // After
       $filter = new UserFilter($request->all());
       $users = User::filter($filter)->get();
       

   • Phase 3: Validation Layer:
     • Add middleware or FormRequest validation to sanitize filter inputs (e.g., whitelist allowed columns).
     • Example:

       public function rules()
       {
           return [
               'status' => 'sometimes|in:active,pending,archived',
               'date' => 'sometimes|date',
           ];
       }
       

   • Phase 4: Documentation:
     • Update API documentation to reflect new filter parameters.
     • Document filter usage for developers (e.g., how to extend Filter classes).
3. Fallback Plan:
   • If integration fails (e.g., conflicts with global scopes, performance issues), implement a custom query builder trait or adopt spatie/laravel-query-builder as an alternative.
   • Example fallback trait:

     trait Filterable
     {
         public function scopeFilter($query, array $filters)
         {
             foreach ($filters as $field => $value) {
                 if (str_contains($field, '>')) {
                     [$field, $operator] = explode('>', $field);
                     $query->where($field, $operator, $value);
                 }
                 // Add more operators as needed
             }
             return $query