Query Filter Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony/Doctrine Alignment: The bundle is tightly coupled with Symfony (4.4/5/6) and Doctrine ORM, making it an excellent fit for Laravel-like PHP applications only if:
  • The application uses Doctrine ORM (not Eloquent).
  • The team is open to adopting Symfony components (e.g., Dependency Injection, Sensio FrameworkExtraBundle) for integration.
  • The goal is to standardize query filtering across a large codebase with complex filtering logic.
• Laravel Compatibility: Laravel’s native query builder (Eloquent) and request handling differ significantly from Symfony’s. Direct adoption would require abstraction layers or a custom wrapper.

Integration Feasibility

• High for Symfony Apps: If the application is already Symfony-based, integration is straightforward (as shown in examples).
• Moderate for Laravel (with Effort):
  • Requires Symfony’s HttpFoundation for request handling (can be mocked or replaced with Laravel’s Illuminate\Http\Request).
  • Doctrine ORM must be used (Laravel’s Eloquent would need a custom adapter).
  • Service Container differences (Symfony’s DI vs. Laravel’s IoC) would need reconciliation.
• Key Dependencies:
  • sensio/framework-extra-bundle (for annotations like @QueryFilter).
  • doctrine/orm (core dependency).
  • jms/serializer-bundle and fos/rest-bundle (for advanced API use cases).

Technical Risk

Key Questions for Adoption

1. Is Doctrine ORM a viable option, or must Eloquent be used?
2. What is the current query filtering complexity? (Simple LIKE vs. advanced nested conditions.)
3. Does the team have experience with Symfony components (e.g., DI, annotations)?
4. Is API-first development a priority (FOSRestBundle integration adds value for APIs)?
5. What is the migration effort for existing Laravel controllers/repositories?
6. Are there existing query builder utilities that could be extended instead?
7. How critical is URL-based filtering (e.g., ?filter[t.name]=Doe) vs. internal service methods?

Integration Approach

Stack Fit

Migration Path

Option 1: Hybrid Integration (Recommended for Laravel)

1. Phase 1: Core Filtering Logic
   • Extract filtering logic from QueryFilterBundle into a Laravel service.
   • Replace Symfony’s Request with Laravel’s Request via a facade.
   • Implement a custom QueryBuilder wrapper to translate Symfony’s DQL to Eloquent.
   • Example:

     // Laravel Service: FilterService.php
     class FilterService {
         public function applyFilters(Builder $query, array $filters) {
             foreach ($filters as $field => $condition) {
                 if ($condition['type'] === 'like') {
                     $query->where($field, 'like', "%{$condition['x']}%");
                 }
                 // ... other conditions
             }
             return $query;
         }
     }
     

2. Phase 2: Repository Integration
   • Modify repositories to use the FilterService instead of QueryFilter.
   • Example:

     // Laravel Repository: ItemRepository.php
     class ItemRepository extends Eloquent {
         public function scopeFilter(Builder $query, array $filters) {
             return app(FilterService::class)->applyFilters($query, $filters);
         }
     }
     

3. Phase 3: API Layer
   • Use Laravel’s API tools (e.g., spatie/laravel-query-builder) for URL-based filtering.
   • Example route:

     Route::get('/items', [ItemController::class, 'index'])
          ->middleware('throttle:60');
     

   • Controller:

     public function index(Request $request) {
         $query = Item::query();
         $query = $this->filterService->applyFilters($query, $request->filter);
         return new LengthAwarePaginator($query->get(), $query->count(), $request->limit);
     }
     

Option 2: Full Symfony Bundle (For Symfony Apps)

1. Install Dependencies:

   composer require symfony/http-foundation symfony/dependency-injection doctrine/orm
   

2. Configure Bundles (config/bundles.php):

   return [
       Artprima\QueryFilterBundle\ArtprimaQueryFilterBundle::class => ['all' => true],
       // ... other Symfony bundles
   ];
   

3. Follow Symfony Examples (as provided in the README).

Compatibility

• Doctrine ORM: Must be used (not Eloquent).
• Symfony Components: Required for annotations, DI, and request handling.
• Laravel Compatibility: Low without abstraction layers. A custom wrapper is essential.
• Database: Works with any Doctrine-supported database (MySQL, PostgreSQL, etc.).

Sequencing

1. Assess Feasibility: Decide between Laravel-native solutions (e.g., spatie/laravel-query-builder) or Symfony integration.
2. Prototype Core Logic: Build a minimal FilterService in Laravel to validate the approach.
3. Repository Migration: Update repositories to use the new service.
4. API Layer: Integrate with Laravel’s API tools (e.g., pagination, serialization).
5. Testing: Validate edge cases (nested filters, sorting, pagination).
6. Performance Benchmark: Compare against native Eloquent queries.

Operational Impact

Maintenance

• Pros:
  • Reduced Boilerplate: Centralized filtering logic simplifies controllers/repositories.
  • Consistent Behavior: Standardized across the application.
  • Symfony Ecosystem: Leverages battle-tested Symfony components.
• Cons:
  • Laravel Overhead: Additional abstraction layers increase complexity.
  • Dependency Bloat: Symfony components may not align with Laravel’s minimalism.
  • Documentation Gap: Limited Laravel-specific guides; requires custom docs.

Support

• Symfony Apps:
  • Low Risk: Actively maintained bundle with community support.
  • Debugging: Familiar Symfony stack (annotations, DI, Doctrine).
• Laravel Apps:
  • High Risk: Custom wrappers may introduce bugs.
  • Debugging: Unfamiliar Symfony patterns (e.g., ConditionManager, QueryFilterArgs).
  • Vendor Lock-in: Tight coupling with Symfony may hinder future Laravel updates.

Scaling

• Performance:
  • Symfony: Optimized for Doctrine’s QueryBuilder; may outperform Eloquent for complex queries.
  • Laravel: Custom adapters could introduce overhead; benchmark required.
• Database Load:
  • Pagination: Uses Doctrine’s Paginator (efficient for large datasets).
  • Indexing: Ensure filtered columns are indexed (e.g., t.name for LIKE queries).
• Concurrency: Stateless design (request-based) scales well with horizontal scaling.

Failure Modes