Laravel Purity Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Decoupled Design: Leverages Laravel’s Eloquent query builder without modifying core logic, adhering to the Single Responsibility Principle (SRP). The package injects filtering/sorting via a filter() method, keeping controllers lean.
  • Query-String First: Aligns with RESTful API conventions and frontend frameworks (React, Vue, Livewire) by exposing filters via URL parameters (e.g., ?filters[title][$contains]=Laravel).
  • Extensibility: Supports custom filters (e.g., NotBetweenFilter), field renaming, and relation-based sorting, making it adaptable to complex schemas.
  • Database Agnostic: Optimized for MySQL, PostgreSQL, MariaDB, and SQLite, with driver-specific fixes (e.g., LIKE query handling).
  • Livewire Integration: Built-in support for Livewire’s reactive filtering (e.g., wire:model.live), reducing frontend-backend synchronization overhead.

• Weaknesses:

  • Performance Overhead: Dynamic query building (e.g., parsing filters[] arrays) may introduce latency for high-cardinality filters or deeply nested relations. Requires benchmarking for production workloads.
  • Security Surface: URL-based filtering could expose unintended query paths if not paired with allowed fields (e.g., filter(['title', 'status'])). Misconfiguration risks SQL injection or excessive data exposure.
  • Complexity for Edge Cases: Advanced features (e.g., nested relations, custom resolvers) may require deep understanding of the package’s internals, increasing onboarding time.

Integration Feasibility

• Laravel Ecosystem Fit:
  • Native Compatibility: Works seamlessly with Laravel 8–13, Eloquent, and Livewire. No breaking changes to existing query logic.
  • API-First: Ideal for Lumen or API resources where filtering/sorting is a core requirement.
  • Admin Panels: Complements packages like Laravel Nova, Filament, or Backpack for dynamic data tables.
• Non-Laravel Stacks:
  • Limited Value: Not applicable to non-PHP stacks (e.g., Node.js, Python). Requires custom middleware for non-Laravel PHP apps.
  • Frontend Dependencies: Frontend teams must adapt to the filters[] query string format (e.g., Axios/React queries).

Technical Risk

• Critical Risks:
  • SQL Injection: If allowedFields are not strictly defined, malicious users could craft queries targeting sensitive columns (e.g., filters[password][$contains]=test). Mitigation: Always whitelist fields and validate input.
  • Performance Regression: Poorly optimized filters (e.g., unbounded LIKE queries) could bloat database load. Mitigation: Test with production-like datasets; use database indexes.
  • Livewire-Specific Bugs: Livewire’s reactive updates might conflict with Purity’s query caching. Mitigation: Test in staging; monitor memory usage.
• Moderate Risks:
  • Version Lock: Laravel 13 support is recent (v3.3.9). Mitigation: Pin to ^3.3 in composer.json until stability is proven.
  • Custom Filter Complexity: Extending with custom filters (e.g., geospatial queries) requires PHP knowledge. Mitigation: Document custom resolver patterns.
• Low Risks:
  • License: MIT license is permissive and poses no legal risk.
  • Documentation: Comprehensive docs and TypeScript examples reduce onboarding friction.

Key Questions

1. Use Case Alignment:
   • Are filtering/sorting requirements dynamic (user-driven) or static (predefined)? Purity excels at the former.
   • Do we need real-time updates (Livewire) or batch processing (queued jobs)? Purity’s Livewire support may not suit async workflows.
2. Performance:
   • What’s the maximum query complexity (e.g., 5 filters vs. 20)? Test with EXPLAIN ANALYZE in PostgreSQL/MySQL.
   • Are database indexes in place for filtered columns? Purity won’t add them automatically.
3. Security:
   • How will we whitelist fields to prevent injection? Example: Post::filter(['title', 'published_at'])->get().
   • Are sensitive fields (e.g., password_hash) accidentally exposed? Audit allowedFields in all queries.
4. Frontend Integration:
   • Can frontend teams adopt the filters[] format? Provide examples for React/Vue/Angular.
   • Will pagination (e.g., ?page=2) conflict with filtering? Purity supports both but requires testing.
5. Maintenance:
   • Who will update the package as Laravel evolves? Assign a tech lead for dependency management.
   • Are there internal alternatives (e.g., custom scopes) that could reduce vendor lock-in?

Integration Approach

Stack Fit

• Primary Fit:
  • Laravel 8–13: Native support with zero configuration for core features.
  • Livewire: First-class integration for reactive filtering (e.g., search-as-you-type).
  • APIs: RESTful query parameters align with frontend frameworks (e.g., useQuery in React Router).
  • Admin Panels: Works with Filament, Nova, or custom Blade tables.
• Secondary Fit:
  • Lumen: Lightweight alternative to Laravel for APIs.
  • Legacy Laravel: Supports v8–10 with minor adjustments.
• Non-Fit:
  • Non-PHP Stacks: Requires custom middleware (e.g., Symfony/PHP-FPM).
  • GraphQL: Purity is query-string focused; GraphQL uses variables. Consider Laravel GraphQL extensions instead.

Migration Path

1. Assessment Phase:
   • Audit existing filtering logic (e.g., manual where() chains in controllers).
   • Identify high-priority endpoints (e.g., product listings, user dashboards) for Purity adoption.
2. Pilot Implementation:
   • Step 1: Replace a single controller’s filtering logic with filter().

     // Before
     if (request('status')) {
         $posts = $posts->where('status', request('status'));
     }
     // After
     $posts = Post::filter()->get();
     

   • Step 2: Test with frontend teams using the new filters[] format.
   • Step 3: Gradually migrate other endpoints, starting with the most complex.
3. Full Rollout:
   • APIs: Deploy Purity-enabled endpoints behind feature flags.
   • Admin Panels: Integrate with Livewire components (e.g., wire:model.live="filters").
   • Documentation: Update API specs and frontend guidelines for the new query format.

Compatibility

• Database Drivers:
  • Supported: MySQL, PostgreSQL, SQLite, MariaDB (tested via GitHub Actions).
  • Unsupported: Older DBAL versions or niche drivers (e.g., Oracle). Workaround: Custom resolvers.
• Laravel Features:
  • Eloquent: Full support for models, relations, and accessors.
  • Scopes: Purity integrates with existing scopes (e.g., Post::withTrashed()->filter()).
  • Caching: Query caching works but may conflict with dynamic filters. Use Cache::forget() for filtered queries.
• Third-Party Packages:
  • Livewire: Native support; no conflicts.
  • Spatie Laravel Query Builder: Purity operates at a higher level and should coexist.
  • API Resources: Purity filters data before serialization.

Sequencing

1. Phase 1: Core API Endpoints
   • Replace manual filtering in public APIs (e.g., /api/products).
   • Priority: High-traffic, high-complexity endpoints.
2. Phase 2: Admin Panels
   • Integrate with Filament/Nova or custom Blade tables.
   • Priority: Dashboards with frequent ad-hoc filtering.
3. Phase 3: Frontend Alignment
   • Update frontend code to use filters[] format.
   • Priority: React/Vue components consuming the API.
4. Phase 4: Edge Cases
   • Custom filters (e.g., geospatial, full-text search).
   • Priority: Low; only if core use cases are stable.

Operational Impact

Maintenance

• Pros:
  • Reduced Boilerplate: Eliminates repetitive where() logic in controllers.
  • Centralized Rules: Filter definitions live in model scopes or global config, not scattered across controllers.
  • Community Support: 515 stars and active maintenance (last release: 2026-03-25).
• Cons:
  • Dependency Management: Requires monitoring for Laravel version compatibility.
  • Custom Logic: Extending Purity (e.g., adding a `Distance