Imported from Thavarshan/filterable (AGENTS.md). Install upstream with npx skills add Thavarshan/filterable. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

Source code lives under src/Filterable/, centred around the abstract Filter base class and trait-based “concerns” under src/Filterable/Concerns/. Contracts and Eloquent helpers are in src/Filterable/Contracts/ and src/Filterable/Traits/. The Artisan generator and stubs are in src/Filterable/Console/. Executable tooling scripts are stored in bin/, shared media in assets/, and tests (plus fixtures) in tests/, which boot an Orchestra Testbench environment. Composer already maps Filterable\\ and the testing namespaces; place any new factories inside database/factories to maintain autoloading.

Build, Test, and Development Commands

Run composer install to hydrate dependencies, then rely on the Composer scripts: composer lint (delegates to bin/lint.sh for Duster + syntax checks), composer fix (formats via Pint/Duster and saves a log), and composer test (wraps bin/test.sh which accepts flags such as --filter=HandlesRateLimitingTest, --coverage, --parallel, or --test=tests/HandlesFilterablesTest.php). When adding commands, keep the scripts directory executable (chmod +x bin/*.sh).

Coding Style & Naming Conventions

Code follows PSR-12 with four-space indentation enforced by Pint/Duster. Match namespaces to paths (Filterable\\Concerns\\OptimizesQueries, etc.) and stick to the existing naming patterns: suffix traits with the capability (ManagesMemory), concrete filters with Filter, and console commands under Console. Keep feature toggles ($features) and options arrays cohesive—extend the existing map rather than inventing new flags. Prefer expressive method-level docblocks when behaviour is subtle (e.g. cache key generation), otherwise lean on descriptive naming.

Testing Guidelines

The suite is PHPUnit-based (phpunit.xml.dist) and runs inside Orchestra Testbench. Follow the established pattern of placing concern-specific tests at the project root (e.g. CachingTest.php, HandlesRateLimitingTest.php) and keep reusable doubles under tests/Fixtures/. Use partial mocks for collaborators (cache, logger, rate limiter) and prefer data providers or inline anonymous filters for edge cases. Generate coverage with ./bin/test.sh --coverage --filter=Namespace\\Class before shipping complex features, and assert on state via getDebugInfo() when relevant.

Commit & Pull Request Guidelines

Commits should be short, imperative sentences (Add smart caching heuristic, Tighten rate limit checks). Keep behavioural, formatting, and tooling changes in separate commits where practical. In pull requests, outline the capability touched (e.g. “Adds new trait”, “Updates generator stub”), document any newly enabled features or config knobs, and list verification commands (composer lint, composer test, extra manual checks). Surface breaking changes or migrations explicitly and attach debug output or SQL snippets if they inform reviewers.