Laravel Purity Laravel Package

Technical Evaluation

Architecture Fit

• Query Abstraction: Laravel Purity elegantly abstracts complex filtering/sorting logic, aligning with Laravel’s Eloquent query builder. This reduces boilerplate and centralizes query logic, improving maintainability.
• Separation of Concerns: The package enforces a clean separation between frontend (URL params) and backend (Eloquent queries), adhering to RESTful principles.
• Extensibility: Supports custom filters, relation fields, and Livewire integration, making it adaptable to complex use cases (e.g., multi-tenant apps, nested relations).
• API-First Design: Inspired by Strapi’s filtering/sorting, it’s well-suited for headless APIs or SPAs consuming Laravel-backed endpoints.

Integration Feasibility

• Low Friction: Requires minimal changes—just add traits (Filterable, Sortable) to models and call filter()/sort() in controllers.
• Backward Compatibility: Works with existing Eloquent queries without breaking existing logic.
• Frontend Agnostic: Frontend teams can use standard query params (e.g., ?filters[title][$contains]=...) or libraries like qs for JavaScript clients.
• Livewire Support: Seamlessly integrates with Livewire for real-time filtering (e.g., dynamic table updates).

Technical Risk

• Performance Overhead:
  • Dynamic query building (e.g., relation filters) may introduce N+1 query risks if not optimized (mitigated by eager loading or package’s built-in optimizations).
  • Complex filters (e.g., nested relations) could impact query plan generation.
• Security:
  • Default "silent" exceptions hide errors, which could mask malicious input (configurable via purity.php).
  • No built-in input validation for filter operators/values (requires manual validation or middleware).
• Versioning:
  • Breaking changes in major versions (e.g., $filterFields restructuring in v3) may require migration effort.
• Testing:
  • Custom filters or relations require thorough unit/integration tests to ensure edge cases (e.g., null values, invalid operators) are handled.

Key Questions

1. Query Complexity:
   • How will the package handle deeply nested relations (e.g., user.posts.tags.name)? Are there limits to relation depth?
   • What’s the performance impact of filtering on large datasets (e.g., 100K+ records)?
2. Customization:
   • Can we override default filter operators (e.g., add $in for array fields) without extending the package?
   • How does the package handle custom Eloquent scopes or global scopes?
3. Frontend Integration:
   • Does the package provide frontend SDKs (e.g., React/Vue hooks) for common filter patterns?
   • How does it handle pagination conflicts (e.g., ?page=1&filters[...])?
4. Monitoring:
   • Are there metrics or logs for slow queries caused by Purity filters?
   • Can we audit filter usage (e.g., track which filters are most/least used)?
5. Alternatives:
   • How does Purity compare to other Laravel packages (e.g., spatie/laravel-query-builder, archtechx/boom) for our use case?

Integration Approach

Stack Fit

• Laravel Ecosystem: Optimized for Laravel 10+ (PHP 8.1+), with native support for Eloquent, Livewire, and API resources.
• Frontend Compatibility:
  • Works with vanilla JS (query params), React/Vue (via qs library), or frameworks like Next.js/Nuxt.
  • Livewire integration enables server-side reactivity without full-page reloads.
• Database Agnostic: Compatible with MySQL, PostgreSQL, SQLite, etc., as long as the underlying Eloquent queries are supported.
• API-Centric: Ideal for REST/GraphQL APIs where clients need flexible filtering/sorting.

Migration Path

1. Assessment Phase:
   • Audit existing queries to identify repetitive filtering/sorting logic.
   • Map current filter operators (e.g., custom scopes) to Purity’s syntax.
2. Pilot Integration:
   • Start with a single model (e.g., Post) to test basic filters/sorts.
   • Gradually replace manual query logic with filter()/sort() calls.
3. Frontend Alignment:
   • Update frontend clients to use Purity’s query param format (e.g., filters[title][$contains]).
   • For Livewire, bind component properties to $filters and sync with the backend.
4. Phased Rollout:
   • Phase 1: Basic filters/sorts (e.g., title, created_at).
   • Phase 2: Relation fields (e.g., author.name, tags.slug).
   • Phase 3: Custom filters or advanced use cases (e.g., full-text search).

Compatibility

• Laravel Versions: Tested on Laravel 10+; may require adjustments for older versions (e.g., PHP 8.0).
• Package Conflicts:
  • Potential conflicts with other query-building packages (e.g., spatie/laravel-query-builder). Use composer’s replace or alias traits to avoid collisions.
  • Ensure no duplicate filter/sort methods exist in models.
• Database Quirks:
  • Some operators (e.g., $like) may behave differently across databases (e.g., PostgreSQL’s ILIKE vs. MySQL’s LIKE).
  • Test with reserved keywords (e.g., order, group) in field names.

Sequencing

1. Setup:
   • Install via Composer: composer require abbasudo/laravel-purity.
   • Publish config: php artisan vendor:publish --tag=purity.
   • Configure silent mode and allowed fields in config/purity.php.
2. Model Integration:
   • Add use Filterable; use Sortable; to target models.
   • Define $filterFields and $sortFields if restricting fields.
3. Controller Updates:
   • Replace manual queries with:

     return Post::filter()->sort()->paginate(10);
     

4. Frontend Updates:
   • Update API calls to include Purity-compatible params (e.g., filters[title][$contains]).
   • For Livewire, bind component properties to $filters and use wire:model.live.
5. Testing:
   • Write integration tests for filter/sort combinations.
   • Test edge cases (e.g., empty filters, invalid operators).
6. Monitoring:
   • Log slow queries to identify performance bottlenecks.
   • Set up alerts for failed filter operations (if silent is disabled).

Operational Impact

Maintenance

• Pros:
  • Centralized filter/sort logic reduces duplication across controllers.
  • Config-driven (e.g., purity.php) allows easy adjustments without code changes.
  • MIT license enables customization without vendor lock-in.
• Cons:
  • Custom filters or relations may require maintenance if the package evolves.
  • Debugging complex queries (e.g., nested relations) could be harder without proper logging.
• Best Practices:
  • Document allowed filters/sorts in API specs (e.g., OpenAPI/Swagger).
  • Use feature flags for experimental filters to avoid breaking changes.

Support

• Proactive Measures:
  • Train frontend teams on Purity’s query syntax (e.g., filters[field][operator]).
  • Provide a runbook for common issues (e.g., "How to debug a failing relation filter").
• Common Issues:
  • Operator Mismatches: Frontend uses $eq but backend expects $equals.
  • Case Sensitivity: $contains vs. $eqc for case-sensitive matches.
  • Relation Errors: Forgetting to define $filterFields in related models.
• Support Channels:
  • GitHub Issues (for package bugs).
  • Community forums (e.g., Laravel Discord) for usage questions.
  • Custom Slack channel for internal escalations.

Scaling

• Performance:
  • Optimizations:
    • Use with() for eager loading in relation filters.
    • Add database indexes for frequently filtered/sorted columns.
    • Cache common filter combinations (e.g., Post::filter(['status' => 'published'])->get()).
  • Limitations:
    • Avoid overly complex filters on large tables (e.g., filters[user.id][$in] with 1M users).
    • Consider read replicas for high-traffic APIs.
• Horizontal Scaling:
  • Stateless design (filters/sorts are request-based) works well with queue workers or horizontal scaling.
  • For Livewire, ensure session storage (e.g., Redis) scales with user load.

Failure Modes