Download the PHP package jerome/filterable without Composer

About Filterable

Filterable is a Laravel package for turning HTTP request parameters into rich, composable Eloquent query filters. The base Filter class exposes a stateful pipeline that you can extend, toggle, and compose with traits to add validation, caching, logging, rate limiting, memory management, and more. Everything is opt-in, so you enable only the behaviour you need while keeping type-safe, testable filters.

Requirements

• PHP 8.3, 8.4, or 8.5
• Laravel 11.x, 12.x, or 13.x components (illuminate/cache, illuminate/contracts, illuminate/database, illuminate/http, illuminate/support)
• A configured cache store when you enable caching features
• A PSR-3 logger when you enable logging (optional)

Installation & Setup

Package auto-discovery registers the FilterableServiceProvider, which contextual-binds the current Request into resolved filters and exposes the make:filter Artisan command. Publish the configuration to set global feature defaults, cache behaviour, or runtime options:

Stubs live under src/Filterable/Console/stubs/ and can be overridden by placing copies in your application's stubs directory.

Highlights

• Publishable configuration (config/filterable.php) to set default feature bundles, runtime options, and cache TTLs that the base filter reads during construction.
• Stateful lifecycle with apply, get, runQuery, reset, rich debug output via getDebugInfo(), lifecycle events (FilterApplying, FilterApplied, FilterFailed), and configurable exception handling.
• Opt-in concerns for validation, permissions, rate limiting, caching (with heuristics), logging, performance metrics, query optimisation, memory management, value transformation, and fluent filter chaining.
• Drop-in Filterable Eloquent scope trait so any model can accept a filter instance.
• Smart caching that builds deterministic cache keys, supports tags, memoises counts, and can decide automatically when to cache complex queries.
• Contextual binding in FilterableServiceProvider makes sure container-resolved filters receive the current HTTP Request; injecting a cache repository or PSR-3 logger auto-enables the relevant features.
• Memory-friendly helpers (lazy, stream, streamGenerator, lazyEach, cursor, chunk, map, filter, reduce) when the memoryManagement feature is enabled.
• First-party Artisan generator with --basic, --model, and --force options to rapidly scaffold filters.

Repository Layout

• src/Filterable/Filter.php – abstract base class orchestrating the filter lifecycle and feature toggles.
• src/Filterable/Concerns/ – traits implementing discrete behaviour (filter discovery, validation, caching, logging, performance, optimisation, rate limiting, etc.).
• src/Filterable/Contracts/ – interfaces for the filter pipeline and the Eloquent scope signature.
• src/Filterable/Traits/Filterable.php – model scope that forwards to a Filter instance.
• src/Filterable/Console/MakeFilterCommand.php & src/Filterable/Console/stubs/ – Artisan generator and overrideable stub templates.
• src/Filterable/Providers/FilterableServiceProvider.php – registers the package and console command via spatie/laravel-package-tools.
• bin/ – executable scripts executed by the Composer lint, fix, and test commands.
• tests/ – Orchestra Testbench suite with concern-focused tests and reusable fixtures in tests/Fixtures/.
• assets/ – shared media used in documentation.
• config/filterable.php – publishable defaults for feature toggles, cache TTL, and runtime options.
• database/factories/ – reserved for additional factories should you extend the package.

Quick Start

1. Generate a filter

--model wires the stub to your Eloquent model. Use --basic for an empty shell or --force to overwrite an existing class.

2. Implement filtering logic

Define protected array $filterMethodMap when you need to alias request keys to method names. Programmatic filters can be appended with appendFilterable('key', $value) before apply() runs. Supplying an Illuminate\Contracts\Cache\Repository or Psr\Log\LoggerInterface to the constructor immediately enables the caching and logging features.

3. Attach the scope to a model

4. Run the filter pipeline

apply() may only be called once per instance; call reset() if you need to reuse a filter. Because the Filter base class uses Laravel's Conditionable trait, you can use helpers such as $filter->when($request->boolean('validate'), fn ($filter) => $filter->enableFeature('validation'));.

Lifecycle & Core API

• apply(Builder $builder, ?array $options = []) binds the filter to a query, merges options, runs enabled concerns, and transitions the state from initialized → applying → applied. Re-applying without reset() raises a RuntimeException.
• get() returns an Illuminate\Support\Collection of results, delegating to caching or memory-managed helpers when those features are active. runQuery() is a convenience wrapper for apply() + get().
• count() respects smart caching (including tagged caches and memoised counts when enabled). toSql() exposes the raw SQL for debugging.
• enableFeature(), enableFeatures(), disableFeature(), hasFeature() toggle concerns per instance; defaults may be set in config/filterable.php and are applied in the constructor.
• setOption(), setOptions() persist runtime flags (for example chunk_size, use_chunking) that concerns such as OptimizesQueries and ManagesMemory consume.
• reset() returns the filter to the initialized state so it can be applied again. getDebugInfo() surfaces state, filters applied, options, SQL/bindings, and metrics.

Feature Guides & API

Validation & Value Transformation

• Enable with enableFeature('validation') and configure with setValidationRules(), addValidationRule(), and setValidationMessages(). Only active filters are validated and ValidationException is rethrown.
• Enable valueTransformation to normalise inputs before filter methods execute. Register per-key transformers with registerTransformer() or bulk-array transforms with transformArray().

Permissions & User Scope

• forUser($user) scopes queries to the authenticated identifier and folds that identifier into cache keys automatically.
• Enable permissions and declare requirements with setFilterPermissions(). Override userHasPermission() in your filter to plug into your authorisation layer; disallowed filters are dropped (and optionally logged) before execution.

Rate Limiting

• Enable with enableFeature('rateLimit'). Defaults allow 10 filters, a complexity budget of 100, and 60 attempts within a 60-second window; decay is ceil(complexity/10) seconds.
• Tune guardrails with setMaxFilters(), setMaxComplexity(), and setFilterComplexity() (array-valued filters multiply complexity). Override resolveRateLimitMaxAttempts(), resolveRateLimitWindowSeconds(), or resolveRateLimitDecaySeconds() for finer control.

Caching & SmartCaching

• Inject an Illuminate\Contracts\Cache\Repository or call enableFeature('caching') to activate caching. TTL defaults to 5 minutes or config('filterable.defaults.cache.ttl'); override per instance with setCacheExpiration().
• Opt into result or count caching via cacheResults() / cacheCount(), and scope invalidation with cacheTags(), clearCache(), and clearRelatedCaches(). Cache keys include sanitised filter values and optional user identifiers from forUser().
• SmartCaching will automatically cache more complex queries (multiple where clauses, joins, select statements) when caching is enabled, while skipping trivial single-clause lookups.

Logging & Performance Metrics

• Inject a PSR-3 logger or call setLogger() + enableFeature('logging') to emit structured lifecycle logs. Hooks such as applyFilterable and cache-building log automatically when logging is active.
• Enable performance to measure execution time, memory usage, and filter count; extend with addMetric() and read via getMetrics() / getExecutionTime().

Query Optimisation & Filter Chaining

• Enable optimization to apply select(), with(), and chunkSize() before filters run; useIndex() can hint MySQL indexes when appropriate.
• Enable filterChaining to queue fluent additions after request-driven filters: where(), whereIn(), whereNotIn(), whereBetween(), and orderBy() are supported.

Memory Management

• Enable memoryManagement for streaming helpers that avoid loading whole result sets into memory: lazy(), lazyEach(), cursor(), stream(), streamGenerator(), chunk(), map(), filter(), reduce().
• executeQueryWithMemoryManagement() underpins get() when chunk_size is set; resolveChunkSize() honours chunk_size options or provided arguments. Call apply() before streaming helpers; misuse raises a RuntimeException.

Pre-Filters & Manual Filters

• Register global constraints with registerPreFilters(); they run before request-driven filters and are logged when logging is enabled.
• Add programmatic filter values with appendFilterable(), or alias request keys to method names via protected array $filterMethodMap on your filter class. asCollectionFilter() returns a callable compatible with collection pipelines when you want to reuse filterables outside of Eloquent.

Debugging & Events

• getDebugInfo() returns state, enabled features, options, SQL, bindings, and (when performance is enabled) metrics. Override handleFilteringException() to decide whether to swallow or rethrow non-validation errors.
• Listen for FilterApplying, FilterApplied, and FilterFailed events around apply() to hook telemetry, notifications, or side effects.

Configuration

The publishable config/filterable.php controls defaults applied during filter construction:

Per-filter overrides always win—call enableFeature(), disableFeature(), setOption(), or setCacheExpiration() inside individual filters when you need different defaults.

Artisan Generator & Stubs

php artisan make:filter scaffolds a filter class under App\Filters by default:

• --basic emits a minimal filter without feature toggles.
• --model=User imports the model and pre-fills a typed constructor parameter.
• --force overwrites an existing class.

Publish customised stubs by copying src/Filterable/Console/stubs/ into your application's stubs/ directory; the command prefers application stubs when present.

Tooling & Scripts

Package maintenance scripts live in bin/ and are surfaced through Composer:

./bin/test.sh accepts --filter=ClassName, --test=tests/FeatureTest.php, --coverage, and --parallel. ./bin/lint.sh --strict exits non-zero when any issue is detected.

Testing

The PHPUnit suite runs on Orchestra Testbench (phpunit.xml.dist). tests/TestCase.php provisions an in-memory sqlite schema (mocks table) and aliases factories under tests/Fixtures/. Each concern has a dedicated test file (for example CachingTest.php, ManagesMemoryTest.php) with partial mocks and fixtures such as MockFilterable, MockFilterableFactory, and TestFilter. End-to-end behaviour is exercised in tests/Integration/, which boots the full filter pipeline (feature defaults, caching, streaming, lifecycle events) against the in-memory database.

Run targeted subsets with:

Add new integration doubles under tests/Fixtures/ to stay aligned with the existing autoloading.

Frontend Usage

Send filter parameters as query strings from your clients:

Contributing

Please review AGENTS.md for contributor expectations around structure, tooling, and workflow. When ready:

1. Fork the repository and create a feature branch (git checkout -b feature/my-change).
2. Run composer lint and composer test (or ./bin/test.sh --coverage) before opening a PR.
3. Describe the capabilities touched, newly exposed options, and verification commands in the pull request body.

License

This project is open-sourced under the MIT license. See LICENSE for the full text.

Authors

• Jerome Thayananthajothy – Thavarshan

See contributors for the full list of collaborators.

Acknowledgements

Inspired by the flexibility of spatie/laravel-query-builder and Tighten's duster tooling.