filterable: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code on how to contribute safely and effectively to this repository.

Project Overview

Filterable is a Laravel package that converts HTTP request parameters into composable Eloquent query filters. The abstract Filter class in src/Filterable/Filter.php orchestrates the pipeline and delegates optional capabilities—validation, caching, logging, rate limiting, query optimisation, memory management, etc.—to traits in src/Filterable/Concerns/. Eloquent models opt in via Filterable\Traits\Filterable, and the make:filter Artisan command (with stubs in src/Filterable/Console/stubs/) scaffolds new filters.

Key Paths

• src/Filterable/Filter.php – lifecycle (apply, get, runQuery, reset) and feature toggles.
• src/Filterable/Concerns/ – concern traits; enable them through $this->enableFeature().
• src/Filterable/Contracts/ & src/Filterable/Traits/ – interfaces and Eloquent integration.
• bin/ – executable scripts used by Composer (lint.sh, fix.sh, test.sh).
• tests/ – Orchestra Testbench suite with fixtures under tests/Fixtures/.

Development Workflow

composer install                # install dependencies
composer lint                   # run Duster + syntax checks via bin/lint.sh
composer fix                    # apply Pint/Duster formatting (logs to file)
composer test                   # run PHPUnit through bin/test.sh

./bin/test.sh --filter=HandlesRateLimitingTest   # focused tests
./bin/test.sh --coverage                         # coverage (requires Xdebug)
./bin/test.sh --parallel                         # parallel runs
./bin/lint.sh --strict                           # non-zero exit on lint issues
vendor/bin/phpstan analyse                       # static analysis (level max)

phpunit.xml.dist defaults to a MySQL connection; provide compatible env vars or stub the driver locally when running the suite.

Architectural Notes

• Filters transition through states (initialized → applying → applied|failed) and cannot be reused without reset().
• Constructor dependencies automatically enable features (Cache ⇒ caching, LoggerInterface ⇒ logging).
• Request keys are mapped to camelCase methods via HandlesFilterables; override $filterMethodMap for custom naming.
• InteractsWithCache builds deterministic cache keys by sorting/sanitising filterables and including user scope; SmartCaching augments this with tag support and heuristic caching.
• ManagesMemory exposes lazy(), chunk(), cursor(), map(), filter(), reduce() for large result sets.
• SupportsFilterChaining queues fluent query constraints that execute after request-driven filters.