Statamic Filter Builder Laravel Package

Getting Started

This is a Statamic addon (not a standalone Laravel package), so the first mental model is: it gives editors a control for saving structured filter/sort definitions, which your Antlers templates then turn into collection queries.

1. Install the fork, not the original:

   composer require cbox/filter-builder
   

   Do not composer require tv2regionerne/statamic-filter-builder — v2.0.0 is a hard fork with a new namespace (Cbox\FilterBuilder) and an independent release line.

2. Confirm the version matrix before anything else. The release notes are internally inconsistent: it says "Complete rewrite for Statamic v6" but also "Requires Statamic 5.x (v6 addon API)". Check composer.json in the tagged release (or DOCUMENTATION.md) for the actual statamic/cms constraint. Requirements are Laravel 12, PHP 8.2+, and the Statamic addon API.

3. Add the fieldtype to a blueprint. Create/Edit a collection blueprint → add the Filter Builder fieldtype → configure available fields. This is where editors build filter/sort rules per entry, page, or Globals set.

4. Read DOCUMENTATION.md first, not the README. The release explicitly points the v1→v2 migration guide there, and it's the canonical source for the Antlers/front-end consumption contract.

5. First real use case: put the field on a listing page, save two or three filter items (e.g. category = news, published_at >= now), then wire the saved value into a {{ collection:... }} tag in your template using the documented syntax. Verify with {{ dump }} on the saved field data before building anything complex.

Implementation Patterns

Editorial configuration, developer-driven query. The intended split is: editors own the filter definitions (which fields, which operators, which values), and you own the rendering — passing the saved structure into scope/collection tags. Keep query-shaping logic in Antlers/Blade partials, not scattered across the blueprint.

Dynamic Values (formerly "Variables"). Use this when a filter needs a runtime value (query string, page context, user field) rather than a literal. v2 adds inline instructions and Antlers syntax examples directly in the UI, so editors can write {get:category}-style values without a Slack message. Prefer this over hardcoding per-field variants.

Scope + field intersection. v2 makes the scope field intersect fields across collections, matching how the fieldtype behaves. Practical pattern: build a shared "filter fields" blueprint partial across collections, and let scope narrow what's offered in each context. Because duplication is now prevented in the editor, you can stop de-duping in templates.

Collection switch memory. Editors switching collections and back retain their previous items. If you were previously persisting/rehydrating filter config manually to work around v1's amnesia, remove that workaround — it now competes with the built-in behavior.

Collapse/expand for large rule sets. With 2+ items the editor shows a Collapse All / Expand All toggle. Nothing to code, but it means you can safely allow 10–20 filter items without editors complaining about scroll fatigue.

Validation feedback. Items with validation errors get a red border in v2. Combine this with your own server-side validation on the field (Laravel Rule) so errors surface in the editor, not at render time in a 500.

Read-only + empty state. When rendering the field read-only (e.g. on a front-end form or static preview), v2 shows helpful empty-state text instead of a blank box. If you were manually hiding empty fields in your templates, you can drop that conditional.

Testing. The package ships Pest 3 (19 tests covering scopes, variable parsing, collection tag hooks). Mirror those patterns for your own integration tests: assert the saved field structure and assert the resulting collection tag output — that's where regressions will actually live.

Gotchas and Tips

• Namespace break is the big one. Tv2regionerne\StatamicFilterBuilder → Cbox\FilterBuilder. Search your codebase for the old namespace before upgrading — custom tags, service providers, event listeners, and any use statements. This is the most likely source of a silent "class not found" after composer update.
• The "Statamic 5.x (v6 addon API)" line is suspect. Treat it as a documentation bug until you verify composer.json. Pin the Statamic major in your composer.json and test the pair in CI rather than assuming the notes are right.
• Fork ≠ upstream. This is now a maintained fork; upstream tv2regionerne/statamic-filter-builder fixes and issues will diverge. Route bug reports to the new repo, and don't cherry-pick from upstream expecting compatibility.
• Vue 3 + @statamic/cms/ui only matters if you're extending the UI. Vanilla usage doesn't touch Vue. If you are adding custom components, build against DragHandle, Combobox, SortableList, etc. — v1 component patterns and Options API code won't port cleanly.
• PHPStan level 9. The package is now strict-typed. If you consume it in a project that runs PHPStan/Pint, expect stricter errors on untyped interactions with the field data — cast your Field values before use.
• Null safety guards changed behavior. v2 adds defensive guards in scope, augment, and field resolution. If v1 "worked" on missing fields by accident, v2 may now return null / empty where you previously got something. Audit templates that assume a filter always resolved.
• Danish translations shipped; English is the source. If you rely on customized strings, override via your own lang files rather than editing vendor — v2 is a rewrite and copy will shift again.
• Cache after upgrade. The fieldtype and its Vue bundle are rewritten — php artisan view:clear && config:clear && cache:clear, then hard-refresh the CP. Stale asset cache is the most common cause of "the editor UI looks broken after upgrade."