Sieve Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Decouples filtering logic from controllers, adhering to SOLID principles (Single Responsibility) by encapsulating query-building logic in reusable filter classes.
  • Leverages Laravel’s Eloquent, ensuring seamless integration with existing query builders, relationships, and scopes.
  • Minimalist design avoids bloat, making it ideal for small-to-medium applications with straightforward filtering needs.
  • Composable filters enable modular query construction, aligning with Domain-Driven Design (DDD) patterns for complex business logic.
  • Supports value mapping, useful for sanitizing/transforming input (e.g., converting UI values to DB-compatible formats).

• Cons:

  • Limited to Eloquent queries—not suitable for raw SQL, non-Eloquent models, or non-Laravel databases (e.g., MongoDB).
  • No built-in validation—relies on Laravel’s validation or manual checks, which could lead to SQL injection risks if not handled carefully.
  • No caching layer for filters, which may impact performance in high-traffic APIs with repeated filter applications.
  • No support for complex joins/aggregations out of the box (e.g., filtering across multiple related tables with subqueries).

Integration Feasibility

• High for Laravel applications using Eloquent, especially those with:
  • APIs or admin panels requiring dynamic filtering (e.g., dashboards, search endpoints).
  • Legacy codebases with repetitive if-else query-building logic.
  • Teams prioritizing clean, maintainable code over rapid prototyping.
• Low for:
  • Applications using raw SQL, non-Eloquent models, or non-Laravel frameworks.
  • Projects needing advanced filtering (e.g., full-text search, geospatial queries, or multi-table aggregations).

Technical Risk

Key Questions

1. Does the application heavily rely on raw SQL or non-Eloquent queries? → If yes, Sieve may not be worth the integration effort.
2. Are there existing query-building patterns (e.g., custom scopes, repositories)? → If yes, assess overlap/conflicts before adoption.
3. What’s the scale of filter complexity? → For simple filters (e.g., where, orderBy), Sieve is ideal. For nested aggregations, consider alternatives like Spatie Query Builder or Laravel Scout.
4. How critical is performance for filtered endpoints? → Profile query plans with/without Sieve to validate overhead.
5. Is the team familiar with Laravel’s service container and dependency injection? → Sieve’s filter registration relies on these concepts; training may be needed.

Integration Approach

Stack Fit

• Best For:
  • Laravel 8+ applications using Eloquent.
  • APIs (REST/GraphQL) or admin panels with dynamic filtering.
  • Teams using DDD or hexagonal architecture, where query logic should be decoupled from controllers.
• Compatibility:
  • Laravel: ✅ Full support (uses service provider, facades, and Eloquent).
  • PHP 8.0+: ✅ Required for named arguments and attributes.
  • Database: ✅ MySQL, PostgreSQL, SQLite (any Eloquent-supported DB).
  • Caching: ❌ No built-in caching; integrate with Laravel Cache manually if needed.
  • Testing: ✅ Works with Pest/PHPUnit (mock Request and test filter chains).

Migration Path

1. Assessment Phase:
   • Audit existing query-building logic (controllers/repositories) for repetitive patterns.
   • Identify 2–3 high-impact endpoints to pilot Sieve (e.g., a product catalog or user dashboard).
2. Pilot Implementation:
   • Install via Composer: composer require aldemeery/sieve.
   • Refactor one controller to use Sieve filters (e.g., replace if-else blocks with filter classes).
   • Test edge cases (empty inputs, invalid values).
3. Full Rollout:
   • Gradually replace query logic across modules.
   • Update API specs/docs to reflect new filter parameters.
   • Deprecate old query patterns via deprecation warnings (e.g., @deprecated in code).

Compatibility Considerations

• Existing Scopes: Sieve filters can compose with existing scopes via when() or unless().

  $query->when($filter->applied(), fn($q) => $q->scope('active'));
  

• Request Binding: Works seamlessly with Laravel’s FormRequest or manual Request binding.
• Third-Party Packages: May conflict if they override Eloquent query behavior (e.g., query observers). Test thoroughly.
• Legacy Code: Use traits or wrappers to adapt existing query logic to Sieve’s pattern.

Sequencing

1. Phase 1: Simple Filters (e.g., where, orderBy).
2. Phase 2: Complex Filters (e.g., nested conditions, value mapping).
3. Phase 3: Global Filter Application (e.g., middleware for API-wide filtering).
4. Phase 4: Testing and Performance Tuning (identify slow filters; optimize with query caching or DB indexes).

Operational Impact

Maintenance

• Pros:
  • Reduced boilerplate: Filters are defined once and reused across endpoints.
  • Centralized logic: Changes to filtering rules (e.g., adding a new field) require updates in one place.
  • Type Safety: PHP 8.1+ attributes (e.g., #[\Sieve\Filter]) enable IDE autocompletion and static analysis.
• Cons:
  • Filter Registry Management: Must track registered filters (e.g., via service provider or config).
  • Debugging Complexity: Nested filters may obscure query generation; use ->toSql() for debugging.
  • Version Pinning: Requires discipline to avoid breaking changes (e.g., filter method signatures).

Support

• Developer Onboarding:
  • Easy: Familiar Laravel devs will grasp Sieve in <1 hour.
  • Hard: Junior devs may struggle with filter composition or query debugging.
  • Mitigation: Provide a cheat sheet for common filter patterns and debugging tips.
• Community Support:
  • Limited: Small package with 138 stars; rely on GitHub issues or Laravel forums.
  • MIT License: Encourages custom forks if needed.

Scaling

• Performance:
  • Minimal Overhead: Filter composition adds ~5–10ms per query (benchmark with DB::enableQueryLog()).
  • Scaling Bottlenecks:
    • N+1 Queries: Ensure filters use with() for relationships.
    • Complex Joins: Avoid overly nested filters (e.g., whereHas with subqueries).
  • Optimizations:
    • Cache frequent filter combinations (e.g., Cache::remember).
    • Use database indexes for filtered columns.
• Concurrency:
  • Thread-Safe: Stateless filters work in queue workers or horizon jobs.
  • Race Conditions: None inherent to Sieve; depends on underlying query logic.

Failure Modes