Statamic Filter Builder Laravel Package

Technical Evaluation

Architecture fit

• The package is a Statamic addon (Laravel-based CMS) that ships a control-panel fieldtype plus a collection tag for building filtered/sorted queries, along with scope/augment hooks into Statamic's query pipeline. That places it squarely in the "faceted content discovery without an external search service" category — appropriate for editorial sites with moderate content volume and no Elasticsearch/Algolia investment.
• v2.0.0 is a complete rewrite, not an incremental release: namespace moves from Tv2regionerne\StatamicFilterBuilder to Cbox\FilterBuilder, the front-end migrates to Vue 3 <script setup> + composables, and the CP UI is rebuilt on public-ish @statamic/cms/ui components (DragHandle, PublishFields, PublishFieldsProvider, Combobox, SortableList).
• Architectural consequence: the package is now tightly coupled to Statamic's internal control-panel component library. That is a deliberate trade (native look and feel, less custom CSS) but it means the dependency surface is broader than Composer metadata suggests — a Statamic minor release can break the authoring UI without any change in this package.

Integration feasibility

• Hard floor: PHP 8.2+, Laravel 12, Statamic 6 (v6 addon API), Node build for CP assets. Any host application on Laravel 11 / Statamic 5 is blocked until that platform upgrade lands first. This is a platform-coupled upgrade, not a package bump.
• The namespace change is a breaking, repo-wide rename. Touchpoints typically include: composer.json require/remove, config/statamic/filter-builder.php (or equivalent) publish path, any app code or custom addons referencing the old FQCN, cached/published views, and — critically — any persisted data that stores the fieldtype handle or serialized config (blueprints, fieldset YAML, content front matter).
• Release-note inconsistency, must resolve before estimation: the notes say "Complete rewrite for Statamic v6" and "Requires Statamic 5.x (v6 addon API)". These cannot both be true without clarification. Either the line means "the 5.x-era addon API that v6 also uses," or it is a typo. This single ambiguity changes the platform prerequisite and therefore the whole migration epic. Do not estimate until the maintainer confirms.

Technical risk

Key questions for the maintainer

1. Statamic 5 or 6 — which is the actual supported target, and is the "5.x (v6 addon API)" line a typo?
2. Is this fork now the canonical package, or is upstream tv2regionerne/statamic-filter-builder still maintained? Will fixes be merged both ways?
3. Is there a documented, tested migration path for stored blueprint/field data, or only for source code?
4. What is the support policy and expected cadence for Statamic minor releases (i.e., who fixes it when @statamic/cms/ui moves)?
5. Is the CP Vue layer covered by any test or CI storyboard, or is manual QA the only gate?
6. Are there breaking changes to the collection tag output shape (not just internals) that would affect Antlers templates?

TPM read: technically credible and a visible quality step up (PHPStan level 9, Pest 3, null-safety guards, Danish i18n), but it arrives as a hard fork + hard break + platform-gated rewrite. Treat as an evaluate-and-pilot, not an adopt.

Integration Approach

Stack fit

• Best fit: Laravel 12 / Statamic 6 / PHP 8.2+ monolith or multi-site install already using Statamic's native collection tags for listing pages and feeling the limits of hand-rolled Antlers filtering.
• Poor fit: any app on Statamic 5 or Laravel ≤11 (blocked); any app that already owns filtering via a search service (this becomes duplicate capability); any team unwilling to own a forked third-party dependency.
• Prerequisite capability check: does the team have Node/Vite build in CI for CP assets, and can it rebuild them on Statamic upgrades?

Migration path (from v1.x / from the upstream package)

1. Freeze and branch. Create a migration branch; do not mix with feature work. Record the current package version and a baseline of rendered filter output on a representative content set.
2. Resolve the Statamic target question (see key questions) before writing code.
3. Swap the dependency: remove tv2regionerne/statamic-filter-builder, require cbox/filter-builder:^2.0.
4. Namespace sweep: grep for the old FQCN across app/, config/, resources/, custom addons, and tests; replace with Cbox\FilterBuilder.
5. Republish config and views to the v2 paths; diff against the previous published copies and port any local customizations deliberately (do not blind-overwrite).
6. Blueprint audit: enumerate every blueprint/fieldset using the fieldtype; confirm handles still resolve. Check content files for stored field config that encodes the old namespace or old option keys (e.g. the Variables → Dynamic Values rename — verify the underlying stored key did not change).
7. Result-parity test: run the baseline query set before/after and diff result sets, specifically for multi-collection setups affected by the new scope-intersection behavior.
8. CP manual QA: drag-and-drop reorder, collapse/expand, duplicate prevention, validation-error borders, dark mode, collection-switch memory, empty/read-only state.
9. Rollback plan: keep the branch revert path clean; the old package must remain installable if the pilot fails.

Compatibility considerations

• Audit other addons for conflicting @statamic/cms/ui versions or global CSS.
• Confirm the collection tag's Antlers signature is unchanged; the "Dynamic Values" rename may be UI-only, but confirm.
• If multi-site is in play, test the new cross-collection scope intersection per site, not just on default.

Sequencing (T-shirt sizing, dependent order)

Do not start at Phase 2 if Phase 1 is not already done — that is the largest and least-controllable piece of the critical path.

Operational Impact

Maintenance

• The dominant ongoing cost is fork ownership ambiguity, not code. Adopting this means taking a position on which upstream is canonical; if the fork stalls, the team inherits a Statamic-internals-coupled addon with no vendor. Budget for "we may have to patch it ourselves" and identify a named owner with Vue 3 + Statamic CP experience.
• PHPStan level 9 and Pest 3 raise the contribution bar (good), but the 19-test suite covers backend scopes/parsing/hooks only. Treat the CP Vue layer as untested code and compensate with a scripted manual regression checklist per Statamic upgrade.
• Expected maintenance triggers: every Statamic minor (CP component changes), every Vue/Pest major, and any @statamic/cms/ui API drift.

Support

• Small, likely one-maintainer project with a fork lineage; expect GitHub-issue-level support, no SLA. Internalize the DOCUMENTATION.md migration guide into your own runbook — external docs are a single file and can lag.
• Danish translation is complete; other locales fall back to English. If non-Danish editors are in scope, plan for translation strings of the new UI copy ("Dynamic Values", inline instructions, empty-state text).

Scaling

• Filtering executes through Statamic's query layer; the new cross-collection scope intersection may produce different (often heavier) field resolution. Watch for N+1 on collection-tag rendering in listing pages and validate with representative content volumes at the 95th percentile, not with a demo dataset.
• No caching layer is described — page/response caching remains the team's responsibility. Confirm cache-key correctness when filters are present in the query string.

Failure modes to monitor

• Silent result drift after the scope-intersection change — wrong content shown, no error. Highest-impact failure; mitigate with the parity diff and an alerting check on result counts.
• CP UI breakage on Statamic minors — editors cannot build filters; degrades to read-only usage of existing config.
• Orphaned blueprint config from an incomplete namespace migration — surfaces as a runtime render error for editors, not at deploy time.
• CSS bleed from dark-mode styles into other CP addons.

Ramp-up

• Backend devs: low — mostly a rename plus config republish (a few days).
• Front-end/CP work: moderate-high — Vue 3 <script setup>, composables, and Statamic's UI component contracts are specialized; assume 1–2 sprints before a developer can safely patch the CP layer.
• Editors: near-zero training, positive — duplicate prevention, collapse-all, collection-switch memory, inline Antlers example, and validation-error highlighting all reduce support tickets. Budget a short demo for the "Dynamic Values" rename since the label and instructions changed.

Recommendation: proceed to a time-boxed pilot (Phases 2–4) only after the maintainer clarifies the Statamic 5/6 target and the fork's canonical status. Gate production adoption on the result-parity diff and editor UAT. Re-assess formally if no maintainer response within two weeks — an unresponsive single-maintainer fork on Statamic-internal APIs is the primary long-term liability.