Filters Laravel Package

Getting Started

1. Install via Composer: composer require spiral/filters.
2. Create your first filter class by extending Spiral\Filters\Filter and defining validation rules in the defineRules() method.
3. Use the Filterable trait on your query builder or collection to apply filters: (new Filterable($query))->apply($filterInstance).
4. Start with request-driven filtering: instantiate your filter using FilterFactory (or make() helper in Spiral apps), passing request data.

Example:

class UserFilter extends Filter
{
    protected function defineRules(): array
    {
        return [
            'status' => ['string', Rule::in(['active', 'inactive'])],
            'role'   => ['string', Rule::in(['admin', 'user'])],
        ];
    }
}

Implementation Patterns

• Composable Pipelines: Chain multiple filters via Pipeline::add() for layered criteria (e.g., UserFilter → DateRangeFilter).
• Conditional Application: Use Filter::onlyWhen($condition) to apply filters only when contextually relevant (e.g., admin-only fields).
• Query Builder Integration: Extend filters to return query constraints (e.g., override apply() to modify QueryBuilder).
• DTO-style Hydration: Use filters to safely hydrate objects from untrusted input—filters validate and transform (e.g., null → 'active', or cast to enum).
• Test Isolation: Unit-test filters independently—verify rules, mappings, and constraints without database interaction.

Gotchas and Tips

• No Auto-Routing: Filters don’t auto-resolve; use explicit instantiation or DI container (make() or InjectorInterface).
• Rule vs. Mapping Confusion: defineRules() handles validation; defineMap() handles input → property mapping. Don’t conflate them—validation without mapping loses data intent.
• Empty Input Handling: Empty/missing keys pass validation by default. Use required() or custom rules if absence is an error.
• Operator Extensibility: Override validateValue() or register custom Rule classes for domain-specific checks (e.g., UniqueEmail).
• Legacy Notice: Last release in 2020—ensure compatibility with newer PHP versions and Laravel (10+). Consider forking if active maintenance is critical.
• Framework Dependency: Despite being a standalone package, its documentation assumes Spiral Framework patterns. Adapt DI/container bindings for non-Spiral apps.