Filterable Laravel Package

Technical Evaluation

Architecture Fit

• Eloquent-Centric Design: The package is tightly coupled with Laravel’s Eloquent ORM, making it ideal for applications where query filtering is a core feature (e.g., admin panels, data dashboards, or APIs). It abstracts complex filtering logic into reusable traits/methods, reducing boilerplate in controllers/repositories.
• Query Builder Agnosticism: While Eloquent-focused, it leverages Laravel’s underlying query builder, ensuring compatibility with raw SQL extensions (e.g., whereRaw) if needed. This avoids vendor lock-in for core filtering logic.
• Separation of Concerns: Encourages filtering logic to reside in models (via traits) or dedicated filter classes, aligning with Laravel’s conventions for modularity. Risk: Overuse in models may violate Single Responsibility Principle (SRP) if filters become too complex.

Integration Feasibility

• Low Friction for Eloquent Apps: Requires minimal setup (composer install + service provider binding). Existing apps using Eloquent will see immediate value with minimal refactoring.
• API/GraphQL Compatibility: Can be adapted for API resource classes (e.g., JsonResource) or GraphQL resolvers by extending filterable models. May need middleware to parse filter inputs (e.g., from $request->query()).
• Legacy System Challenges: Apps using raw SQL or non-Eloquent queries (e.g., DB facades directly) will require wrapper layers to leverage this package.

Technical Risk

• Performance Overhead: Dynamic query building (e.g., applyFilters()) may generate inefficient SQL if filters are not optimized. Risk mitigated by:
  • Caching compiled filter conditions (e.g., via Laravel’s query caching).
  • Validating filter inputs early (e.g., using Laravel’s ValidatesRequests).
• Security Risks:
  • SQL Injection: If filter values aren’t sanitized (e.g., allowing raw SQL in whereRaw). Mitigate with input validation and parameter binding.
  • Mass Assignment: Filterable fields must be explicitly whitelisted to avoid unintended model attribute updates.
• Versioning Risk: Package is actively maintained (2025 release), but breaking changes could occur. Recommend pinning versions in composer.json and testing upgrades.

Key Questions

1. Filter Complexity: How many dynamic filters will be used? For >50 filters, consider a hybrid approach (e.g., package for simple filters + custom logic for complex ones).
2. Input Sources: Will filters come from:
   • Frontend forms (structured inputs)?
   • API queries (unstructured, e.g., ?filter[field]=value)?
   • Both? (Requires input normalization.)
3. Caching Strategy: Will filtered queries be cached? If so, how will cache keys handle dynamic filter combinations?
4. Testing Coverage: Does the team have experience testing query builders? Dynamic filters may require unique test cases (e.g., edge cases for null values, nested relationships).
5. Monitoring: How will query performance be monitored post-integration? Slow filters could degrade API responses.

Integration Approach

Stack Fit

• Laravel Ecosystem: Native support for Eloquent, service containers, and request handling. Integrates seamlessly with:
  • APIs: Use with Laravel’s Resource classes or API controllers.
  • Frontend Frameworks: Works with Vue/React via API endpoints or direct model usage (e.g., Inertia.js).
  • Queues/Jobs: Filterable models can be used in background jobs (e.g., generating reports).
• Non-Laravel PHP: Limited utility outside Laravel due to Eloquent dependency. Could be adapted for raw PDO queries with significant effort.

Migration Path

1. Pilot Phase:
   • Start with a single high-impact model (e.g., User or Order).
   • Implement basic filtering (e.g., name, status, created_at).
   • Test with both API and frontend inputs.
2. Incremental Rollout:
   • Add filterable traits to additional models, prioritizing those with complex query logic.
   • Replace custom query methods (e.g., scopeActive()) with package equivalents.
3. Refactor Legacy Logic:
   • Replace ad-hoc where clauses in controllers with centralized filter definitions.
   • Example:

     // Before
     $users = User::where('status', 'active')->where('role', 'admin')->get();
     
     // After
     $users = User::filter($request->query('filter'))->get();
     

Compatibility

• Laravel Versions: Tested with Laravel 10/11 (per 2025 release). May require adjustments for older versions (e.g., <9.x).
• Database Support: Works with all databases supported by Eloquent (MySQL, PostgreSQL, SQLite, etc.). No vendor-specific features.
• Third-Party Conflicts:
  • Query Scopes: Ensure no naming collisions with existing model scopes (e.g., scopeActive vs. filterActive).
  • Middleware: If using API filter parsing middleware, ensure it doesn’t conflict with other middleware (e.g., CORS, auth).

Sequencing

1. Setup:
   • Install package: composer require ysm/filterable.
   • Publish config (if any) and bind service provider.
2. Model Integration:
   • Use the Filterable trait in target models.
   • Define filter rules in filterRules() method.
   • Example:

     use YSM\Filterable\Traits\Filterable;
     
     class User extends Model
     {
         use Filterable;
     
         protected function filterRules()
         {
             return [
                 'name' => ['like'],
                 'status' => ['eq'],
                 'created_at' => ['gte', 'lte'],
             ];
         }
     }
     

3. Controller/API Layer:
   • Pass filter inputs to model:

     $users = User::filter($request->input('filters'))->paginate();
     

   • For APIs, validate inputs using Laravel’s Validator or FormRequest.
4. Testing:
   • Unit test filter rules and edge cases (e.g., invalid operators).
   • Integration test with frontend/API consumers.

Operational Impact

Maintenance

• Pros:
  • Centralized Logic: Filter rules live in models, reducing duplication across controllers.
  • Consistent Behavior: Standardized filtering reduces bugs from ad-hoc queries.
• Cons:
  • Model Bloat: Complex filter rules may make models harder to read. Mitigate by:
    • Moving rules to separate classes (e.g., UserFilter).
    • Using comments to document filter purposes.
  • Dependency Risk: Package updates may require model adjustments (e.g., breaking changes in trait methods).

Support

• Debugging:
  • Query Logs: Enable Laravel’s query logging to inspect generated SQL.
  • Filter Validation: Add logging for invalid filter inputs (e.g., unsupported operators).
• Common Issues:
  • Performance: Slow queries due to unoptimized filters (e.g., like on large text fields).
  • Edge Cases: Filters with null values or nested relationships may need special handling.
• Documentation: Package lacks extensive docs; team will need to:
  • Document custom filter rules.
  • Create runbooks for troubleshooting (e.g., "Filter X is slow because of Y").

Scaling

• Horizontal Scaling:
  • Stateless filters work well in distributed environments (e.g., queues, load-balanced APIs).
  • Caching filtered results (e.g., Redis) can reduce database load.
• Database Load:
  • Risk: Complex filters (e.g., nested orWhere) may cause query plan issues.
  • Mitigation:
    • Use database indexes for filtered columns.
    • Implement query timeouts for long-running filters.
• API Scaling:
  • Filter parsing in middleware adds minimal overhead. Monitor latency under high traffic.

Failure Modes

Ramp-Up

• Onboarding:
  • For Developers:
    • 1–2 hours to understand trait usage and filter rules.
    • Hands-on workshop to build a sample filtered endpoint.
  • For QA:
    • Focus on testing edge cases (e.g., empty filters, malformed inputs).
    • Automate filter validation in CI (e.g., test all operators for each rule).
• Training Materials:
  • Create internal docs with:
    • Code snippets for common filter patterns.
    • Examples of integrating with APIs/frontends.
    • Troubleshooting