Filters Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require adimeo-data-suite/filters
   

   Requires adimeo-data-suite/commons (install via composer require adimeo-data-suite/commons).

2. First Use Case: Filtering Collections

   use Adimeo\DataSuite\Filters\Filter;
   use Adimeo\DataSuite\Filters\FilterCollection;
   
   $collection = collect([1, 2, 3, 4, 5]);
   $filter = new Filter('>', 3); // Greater than 3
   $filtered = (new FilterCollection())->add($filter)->apply($collection);
   // Returns: [4, 5]
   

3. Where to Look First

   • Core Classes: Filter, FilterCollection, Rule, RuleCollection.
   • Documentation: Check the source code for examples (limited but practical).
   • Commons Dependency: Review adimeo-data-suite/commons for shared utilities (e.g., DataObject).

Implementation Patterns

1. Filtering Collections

$filterCollection = (new FilterCollection())
    ->add(new Filter('!=', 'status', 'active')) // Exclude active
    ->add(new Filter('>', 'price', 100));       // Price > 100

$results = $filterCollection->apply($usersCollection);

2. Dynamic Filtering (e.g., API Requests)

$requestFilters = $request->input('filters', []);
$filterCollection = (new FilterCollection())
    ->fromArray($requestFilters); // Parses ['field>value', 'field!=value']

$filteredData = $filterCollection->apply($model->getQuery());

3. Integration with Eloquent

use Adimeo\DataSuite\Filters\Eloquent\QueryBuilder;

$query = User::query();
$filterCollection = (new FilterCollection())->fromArray($request->filters);
$queryBuilder = new QueryBuilder($filterCollection);
$queryBuilder->apply($query);

4. Custom Rules

use Adimeo\DataSuite\Filters\Rule;

$customRule = new class implements Rule {
    public function apply($value, $data): bool {
        return str_contains($data['name'], $value);
    }
};
$filterCollection->add(new Filter('contains', $customRule));

5. Caching Filters (Advanced)

$filterCollection->setCacheKey('user_filters_' . $request->user()->id);
$filtered = $filterCollection->apply($collection, 3600); // Cache for 1 hour

Gotchas and Tips

Pitfalls

1. No Built-in Validation

   • Filters accept raw input (e.g., fromArray). Validate/sanitize user-provided filters to avoid SQL injection or logic errors.
   • Example:

     $safeFilters = collect($request->filters)->map(fn($v) => htmlspecialchars($v));
     

2. Eloquent Integration Quirks

   • The Eloquent\QueryBuilder assumes standard Laravel query methods (e.g., where, orWhere). Complex relationships may require custom rules.
   • Test with nested relationships:

     $filterCollection->add(new Filter('>', 'posts.published_at', now()->subDays(7)));
     

3. Performance with Large Datasets

   • Filters apply in-memory by default. For databases, use the Eloquent integration to leverage query optimization.
   • Avoid chaining filters on unindexed columns.

4. Operator Limitations

   • Not all operators (e.g., LIKE, IN) are supported out-of-the-box. Extend Rule for custom logic.

Debugging Tips

• Log Filter Output:

  $filterCollection->debug(); // Dumps applied filters (if enabled in config).
  

• Test Incrementally: Add one filter at a time to isolate issues:

  $filterCollection->add($filter)->apply($collection); // Test each step.
  

Extension Points

1. Custom Operators

   Filter::addOperator('startsWith', function ($value, $data) {
       return str_starts_with($data, $value);
   });
   

   Usage:

   $filter = new Filter('startsWith', 'prefix_');
   

2. Override Default Behavior

   • Extend FilterCollection to add middleware:

     class CachedFilterCollection extends FilterCollection {
         public function apply($data, $ttl = null) {
             return Cache::remember("filters_{$this->getCacheKey()}", $ttl, fn() => parent::apply($data));
         }
     }
     

3. Integrate with API Platform

   • Use the fromArray method to parse OpenAPI filter definitions:

     $filterCollection->fromArray($context['filters']);
     

Config Quirks

• No Default Config: The package is lightweight; configure via code (e.g., default operators, cache drivers).
• Symfony CSS Selector Dependency: Only used for HTML/XML filtering. Ignore if not needed.