- How do I install Laravel Purity and add filtering to an Eloquent query?
- Install it with composer require abbasudo/laravel-purity, then publish the config file so config/purity.php is available for customization. Add the Filterable trait (and Sortable if you need sorting) to your model, then call Post::filter() or Post::sort() on any query. Once the macro is in place, frontend users can pass parameters like filters[title][$contains]=Purity or sort[0]=created_at:desc directly in the URL. The docs cover installation, filter operators, relations, restricting fields, and custom filters.
- Which Laravel and PHP versions does abbasudo/laravel-purity support?
- The package is a thin layer over Eloquent's query builder, so it tracks Laravel closely, but you should verify the exact PHP and Laravel constraints in the package's composer.json and on Packagist before adopting. The technical review of this package specifically flagged confirming support for your current and next Laravel major as a spike task, since breaking changes have occurred across majors. The documentation includes an upgrade guide for each major version, and pinning an exact major is recommended.
- How do I restrict which columns users can filter or sort on in Laravel Purity?
- Define $filterFields and $sortFields on each model to whitelist the columns and relations clients are allowed to touch. This is essential because calling Post::filter() without restrictions gives access to all available filters by default. Note that in v3 the $filterFields property changed semantics from renaming fields to restricting them, so read the upgrade guide when moving from v2. Treat these properties as a mandatory code-review gate on every model that uses the package.
- How does Laravel Purity handle filtering on relationships such as hasMany or belongsTo?
- Purity supports dot notation in filter keys to reach related models, so a query string can target fields on joined or nested relations. The technical review recommends prototyping on hasMany and many-to-many relations before shipping, because relation filtering can inflate row counts or produce non-deterministic ordering. Verify whether the implementation uses whereHas subqueries or joins, and confirm that pagination totals and duplicate rows behave as expected on those endpoints.
- What happens when a user sends an invalid or disallowed filter in Laravel Purity?
- By default the package runs with 'silent' => true, meaning malformed or non-whitelisted filters are quietly dropped rather than surfaced as errors. Set silent to false in config/purity.php for non-production environments so you can see exactly what is being rejected, and consider a request-level assertion in tests that no filter keys were silently discarded. The review also suggests confirming whether silent mode false throws a typed exception you can map to a 400 or 422 response, or whether you need to wrap the macro call to log rejections.
- Can I use Laravel Purity with Livewire components and pagination?
- Yes, Livewire support is documented, and the pattern is to pass the $filters array explicitly into the filter() macro rather than relying on the request automatically. Because Purity returns a normal Eloquent builder, you can chain paginate(), cursorPaginate(), or your own scopes after it. That also means existing Form Requests, API Resources, and repository layers keep working unchanged, since the package has no opinion on HTTP or serialization.
- Is Laravel Purity safe to use in a public or multi-tenant API?
- Purity is a query-string grammar, not an authorization layer, and its default posture is permissive, so it should not be the boundary that enforces tenancy or access control. Restrict fields and operators explicitly, keep authorization in policies and query scopes, and avoid patterns like filters[tenant_id] that let clients influence scoping. The recommended position is to adopt it with guardrails on internal or back-office read APIs first, not as the default in a public multi-tenant API. Also consider rate limits, input arity checks, and indexing for leading-wildcard $contains filters and sorts on unindexed columns.
- How do I test filtering and sorting endpoints built with Laravel Purity?
- Because filter() and sort() are just query builder macros, you can write ordinary feature tests that hit your endpoint with a query string and assert the JSON or pagination output. Set silent to false in your testing environment so rejected filters fail loudly instead of disappearing, and add assertions around count totals on relation-based filters. The package ships with a GitHub Actions test workflow, and community tutorials and a walkthrough video are available if you want reference examples.
- Can I add custom filter operators or customize field behavior in Laravel Purity?
- Yes, the package documents custom filters and the filterBy mechanism so you can add or limit operators per endpoint instead of exposing the full set everywhere. You can also restrict the allowed columns through $filterFields and $sortFields on each model. When upgrading, check the upgrade guide, because v2 changed the filter() arguments and v3 changed $filterFields from rename semantics to restrict semantics.
- What are the alternatives to Laravel Purity and is the package actively maintained?
- The most common comparison is Spatie's Laravel Query Builder, which exposes a similar filter and sort API but with a different configuration and safety model. Laravel Purity is MIT licensed, has third-party coverage from Laravel News and several tutorials, and is maintained by a single author with zero dependents recorded on Packagist, which the review flags as a medium risk. Its small footprint makes vendoring or forking cheap, so plan a fallback and keep your adoption surface small, especially when crossing major versions.