Statamic Livewire Filters Laravel Package

Technical Evaluation

Architecture fit

• The package fits Laravel applications that use Statamic as the content layer and Livewire for interactive front-end components. It is specifically designed for filtering Statamic collections through Livewire, so it aligns well with teams already standardized on the TALL/Statamic stack.
• v4.6.0 materially improves the package’s security posture by hardening client-supplied filter state before Statamic queries run. This makes the package more defensible for production use where filter state can be manipulated via URL or Livewire payloads.
• The new blocked_query_params blocklist, allowed_filters escape hatch, #[Locked] identity properties, protected setParameters(), and rejection of Antlers-evaluated : keys reduce the risk of query-control injection through Statamic parameters such as status, from, site, limit, paginate, filter, since/until, and similar keys.
• Dynamic range bounds are a useful product capability for faceted search, but remain opt-in. This keeps default query complexity stable while allowing product teams to enable adaptive range sliders when the UX benefit justifies the additional query work.

Integration feasibility

• Integration is straightforward for existing users of the package: the release is primarily hardening plus opt-in functionality. Most teams should be able to upgrade without application code changes beyond cache-clearing steps.
• Teams with custom Livewire subclasses or published range views need to make targeted changes: method signatures for filterUpdated(), clearFilter(), and clearFilters() gain an optional $boundsSelection = null parameter; published lf-range.blade.php or lf-dual-range.blade.php views need the range-bounds-updated listener if dynamic bounds are enabled.
• Projects that expose Statamic control-like query keys intentionally through the URL must configure allowed_filters. For example, if visitors are allowed to change limit, that key must be allowed explicitly.
• Projects that filter on a field named like a Statamic control key, such as status:is, must remove that key from blocked_query_params or allow it through allowed_filters. This is a plausible edge case for content-heavy sites with custom filter fields.

Technical risk

• The highest-risk upgrade issue is cache state. If configuration is cached, php artisan config:clear or php artisan config:cache must be run after updating; otherwise the new blocklist stays unset and nothing is blocked. This creates a false sense of security if deployment procedures skip config cache refresh.
• Static caching must also be cleared. Pages cached under 4.5.1 could otherwise drop tag control params such as limit or site on the first filter change. This is an operational risk more than a code risk, but it can produce confusing production behavior immediately after release.
• The blocklist changes query behavior by default. Sites that rely on client-supplied control keys can experience unexpected filtering changes unless allowed_filters is configured. This should be treated as a product-behavior change requiring validation, not just a library upgrade.
• Locking identity properties and making setParameters() protected are positive security changes but may break custom client-side or subclass integrations that depended on mutating those values.
• The changed event semantics around no-op events and filter-updated can affect custom UI logic. If a team previously dispatched filter-updated to force a refresh, they need to call Livewire’s $refresh on the collection instead.
• Dynamic range bounds add query complexity and an encrypted bounds query payload. It is opt-in, but teams enabling it should validate performance and cache behavior on large collections.

Key questions

• Which Statamic query-control parameters, if any, must remain client-addressable through the URL or Livewire state? These must be deliberately allowed via allowed_filters.
• Do any filters target fields named like control keys, such as status:is or limit? If so, what is the allowlist/blocklist exception strategy?
• Are there custom subclasses overriding filterUpdated(), clearFilter(), or clearFilters()? Do they need signature updates?
• Are published range views in use, and will dynamic range bounds be enabled?
• Does the deployment pipeline reliably clear and rebuild config cache and Statamic static cache after package updates?
• Do custom filter components need to listen for clear-all-filters so “Clear all” resets their controls?
• Are any custom listeners consuming params-updated with one argument only? They should remain compatible, but the new second argument should be understood.
• What is the expected performance impact if dynamic range bounds are enabled on high-cardinality collections?

Integration Approach

Stack fit

• Best fit: Laravel + Statamic + Livewire applications that want server-driven faceted filtering without building custom query-hardening and filter-state management from scratch.
• The package is less suitable for teams not using Statamic collections or Livewire, and it should not be treated as a generic filtering layer outside that stack.
• v4.6.0 strengthens the package’s fit for security-conscious production environments by defaulting to blocked Statamic query-control keys and sanitizing URL filter state on page load.

Migration path

• Treat v4.6.0 as a security and behavior-hardening release with a small set of targeted breaking changes.
• Required deployment steps: update the package, run php artisan config:clear or php artisan config:cache, and clear Statamic static cache with php please static:clear.
• Audit blocked_query_params against existing filter fields. If a legitimate filter key is blocked, either remove it from the blocklist or add it to allowed_filters.
• Audit any URL-driven control parameters. If visitors are expected to change limit, site, status, or similar keys through the URL, add those keys to allowed_filters along with normal filter keys.
• Update custom subclasses for the new optional $boundsSelection = null parameter on filterUpdated(), clearFilter(), and clearFilters().
• If dynamic range bounds will be used and range views were published, merge the range-bounds-updated listener or re-publish lf-range.blade.php and lf-dual-range.blade.php.
• Review custom filter components for clear-all-filters handling so “Clear all” resets their internal controls as expected.
• Replace any reliance on dispatching filter-updated solely to force a refresh with Livewire’s $refresh on the collection.

Compatibility

• Existing one-argument params-updated listeners remain compatible; the event now also carries hardened parameters and a second argument for the encrypted bounds query.
• The #[Locked] change on filter identity properties may break custom code that mutated field, condition, modifier, collection, blueprint, or statamic_field from the client side. That is intentional hardening and should be treated as unsupported behavior going forward.
• setParameters() becoming protected prevents client invocation. Any custom front-end integration calling it directly must be refactored.
• The new blocklist matching logic applies to the segment before the first colon, so blocking status also blocks status:is. This is important for teams with colon-namespaced filter keys.
• allowed_filters now checks each active query scope independently, fixing a prior issue where two active scope filters could drop both scopes. This is a behavior fix, but teams relying on the old behavior should validate scope filtering after upgrade.

Sequencing

1. Inventory current filter parameters, URL-exposed parameters, custom subclasses, published views, and custom filter components.
2. Upgrade the package in a staging environment and clear config/static caches.
3. Run regression tests for filtering, faceted counts, URL restore, range sliders, “Clear all,” and custom filter components.
4. Configure blocked_query_params exceptions and allowed_filters for any legitimate control keys or colon-namespaced fields.
5. Update subclass method signatures and published range views as needed.
6. Enable enable_dynamic_range_bounds only after functional and performance validation on representative content sets.
7. Deploy with cache-clearing steps baked into the release process.
8. Monitor filter behavior, error logs, and query performance immediately after release.

Operational Impact

Maintenance

• Routine maintenance is low for teams already on the package, but v4.6.0 adds explicit configuration and cache-clearing responsibilities.
• The blocked_query_params blocklist is populated by default and requires no configuration for standard use. However, teams with custom control-key behavior must maintain allowed_filters and blocklist exceptions deliberately.
• Custom subclasses and published range views create ongoing maintenance overhead because upstream signature or view changes may need to be merged.
• Because allowed_filters now checks each active query scope independently, filter configurations with multiple scope filters should be regression-tested and documented.

Support

• Support burden may temporarily increase after upgrade due to cache-related false negatives: if config cache is not refreshed, the new blocklist is unset and nothing is blocked; if static cache is not cleared, cached pages may drop tag control params on first filter change.
• Support teams should be briefed on common upgrade fixes: clear config cache, clear static cache, add allowed_filters for intentionally client-addressable control keys, and adjust blocked_query_params for fields named like control keys.
• Documentation should point to the new guide section on securing parameters and to CHANGELOG.md.
• Custom component teams need guidance on clear-all-filters and range-bounds-updated events.

Scaling

• Default filter queries should remain stable because dynamic range bounds are opt-in.
• Enabling dynamic range bounds may increase query cost on large collections or high-cardinality range fields. Teams should benchmark before enabling broadly.
• The release reduces some client/server chatter: removing a filter or clicking “Clear all” now updates the collection in one Livewire round trip instead of two. This is a modest but useful scalability and UX improvement.
• Faceted counts now use the same filtered state as the entries query, which improves consistency but should be monitored on large result sets if enable_filter_values_count is on.
• When enable_filter_values_count is off, the count listener does nothing, which avoids unnecessary work.

Failure modes

• Config cache not cleared after update: new blocklist remains unset and query-control injection is not blocked. This is the primary security failure mode.
• Static cache not cleared after update: pages cached under 4.5.1 may drop tag control params such as limit or site on first filter change.
• Legitimate filter key blocked by default: filters silently fail or return broader results until the key is allowed.
• Field named like a control key, such as status:is: filtering can break unless the key is removed from blocked_query_params or allowed through allowed_filters.
• Custom subclass overrides without the new optional parameter: method signature mismatches can cause runtime errors.
• Published range views missing the range-bounds-updated listener: dynamic range bounds may not update the custom UI correctly.
• Custom filter components not listening for clear-all-filters: “Clear all” may clear core filters but leave custom component controls active.
• Custom code calling setParameters(): will fail because the method is now protected.
• Custom code dispatching filter-updated only to force a refresh: no re-render will occur when the event changes nothing; use Livewire $refresh instead.

Ramp-up

• Teams already familiar with Statamic and Livewire should ramp up quickly. The main learning is the distinction between normal filter keys, control keys, blocklisted keys, and allowed_filters.
• Developers should review the upgrade notes and the securing-parameters guide before deployment.
• Product and QA teams should test URL-restored filter state, toggle filters with numeric or boolean preset_value, range slider reset behavior, “Clear all,” custom filter components, and faceted counts.
• If dynamic range bounds are adopted, product teams should validate the UX around disabled sliders, selection preservation, and the new range-bounds-updated event before enabling it for all users.