Filterable Laravel Package

Product Decisions This Supports

• User-facing advanced filtering / saved segments: Filterable's Tree engine handles nested boolean groups (AND/OR), which maps directly to "advanced search," saved views, and segment-builder features. v3.0.1 corrects group semantics so a user's declared AND/OR logic is actually honored when direct children are joined — this is table stakes for any filter UI where results must match the user's mental model.
• Roadmap sequencing for search/filtering: Because recursive query construction now preserves nested group boundaries, teams can ship progressively richer filter builders (e.g., (A AND B) OR (C AND (D OR E))) without a custom expression engine on the roadmap.
• Build vs. buy: Leans buy/adopt for Laravel applications. A patch release fixing core boolean-group evaluation signals the Tree engine is still being hardened, but it also means you avoid owning the parser, recursion, and permassive/permissive-mode edge cases yourself.
• Graceful degradation in permissive mode: The fix that omits rejected leaves while retaining valid conditions in the same group supports "best-effort results" UX — important for search experiences where returning zero results due to one invalid clause is a poor experience.
• Risk/trust decision for analytics-facing features: Incorrect AND/OR joining is a silent-wrong-results bug class. Product should treat this as a correctness prerequisite before exposing boolean filtering to customers, and add regression coverage around nested groups.
• Use cases: admin dashboards, CRM/list views, reporting filters, saved audiences, API query-parameter filtering, internal tools where non-engineers compose filters.

When to Consider This Package

Adopt when:

• The application is Laravel/PHP and filtering is defined primarily through model/query-builder filters.
• Users need nested boolean logic or a filter-builder UI, not just a handful of fixed where clauses.
• You want permissive-mode behavior (partial matching rather than all-or-nothing) for search UX.
• You value not maintaining a custom recursive query-construction layer.

Proceed with diligence when:

• The package is on a v3 line and still shipping patch releases that change core group semantics — add your own regression tests for nested AND/OR and permissive mode before relying on it in customer-facing paths.
• Filter structures are persisted (saved segments) — confirm compatibility guarantees as the engine evolves.

Look elsewhere when:

• Filtering needs are simple and static; a few scoped query methods are cheaper than a dependency.
• You need search relevance, full-text ranking, or aggregation semantics better served by a dedicated search engine (Elasticsearch/Meilisearch) rather than query-builder filtering.
• The stack is not Laravel, or filtering must work across heterogeneous data stores.
• You require vendor-backed SLAs or a large maintainer base — validate maintenance risk first.
• Your filter grammar is highly domain-specific or must round-trip through an external query language.

Upgrade posture for v3.0.1: Low risk. No new public APIs or breaking changes; existing Tree request structures remain compatible. Upgrade via composer update kettasoft/filterable and prioritize regression tests on nested groups and permissive-mode omissions.

How to Pitch It (Stakeholders)

For executives: This package lets us ship advanced, user-composed filtering — nested AND/OR groups, saved segments, forgiving "best match" behavior — without building and maintaining a query engine ourselves. The v3.0.1 patch is a low-risk correctness fix: it makes filter groups respect the logic users actually specify, which protects trust in results. No API changes, no migration work; adoption is a composer update plus test coverage. Net effect: faster delivery of a differentiated search/filter experience at reduced engineering risk.

For engineering: v3.0.1 is a patch to the Tree engine: direct children now use the group's declared AND/OR, nested groups retain their boundaries during recursion, and permissive mode drops rejected leaves while keeping valid conditions in the same group. No breaking changes; existing request structures are compatible. Recommended actions: upgrade, add regression tests for nested boolean groups and permissive-mode partial matches, and document the filter grammar contract so persisted saved filters stay stable as the package matures.