Basic Query Filter Laravel Package

Product Decisions This Supports

• Ship user-defined filtering without building a parser. Any roadmap item that lets customers narrow a collection — “show me orders where status is failed and total > 500” — needs a grammar, tokenizer, and AST. This package is a candidate to satisfy that need rather than spending a sprint or two of engineering on a bespoke parser.
• Build vs. buy for search/filter UX. If the product direction is an “advanced search” panel, saved views, or per-tenant filter presets, the filtering language is a shared primitive. Deciding whether to own it (fork/vendor) or adopt an off-the-shelf parser is a roadmap-level call, not a line-item ticket.
• API surface decisions. Supports choosing a filter dialect for public/partner APIs (e.g., filter=status:active AND created>2024-01-01) versus a fixed set of query params. This affects API versioning, documentation, SDK design, and backward-compatibility obligations.
• Feature scope for admin and internal tooling. Back-office list screens, support dashboards, and moderation queues benefit from expressive filtering at low cost; this is often the lowest-risk place to pilot a query language before exposing it to customers.
• Roadmap sequencing for reporting/segments. Saved filters are the foundation for segments, alerts, and scheduled reports. Whether the filter parser is a throwaway or a long-lived component determines how much rework sits between “filterable list” and “saved segment + notification” features.
• Risk budgeting and total cost of ownership. The package is a 2017-era, low-adoption (14 stars), unmaintained library with an Unlicense. The decision is not “is it good?” but “are we willing to own it?” — that answer changes staffing, security review, and upgrade planning for the PHP platform roadmap.

When to Consider This Package

Consider it when:

• The grammar you need is genuinely basic — comparison operators, boolean AND/OR/NOT, grouping — and you do not need full-text relevance, fuzzy matching, faceting, or geo queries.
• You want a small, dependency-light reference implementation to study, vendor, or fork rather than a framework-coupled dependency. A permissive public-domain license (Unlicense) means no attribution burden and no legal friction for commercial embedding.
• You are prototyping or validating a filter-UX concept and can accept the maintenance risk in exchange for a fast start; the parser can be replaced behind a stable internal interface later.
• Your stack is PHP and you are comfortable pinning/vendoring — i.e., you will copy the code into your repo, add tests, and treat it as internal code you own.
• You need server-side parsing of a user-entered filter string rather than simple whitelisted query params, and you want the AST boundary (parse once, validate, then translate to a query builder) as a deliberate design point.

Look elsewhere (or build) when:

• Maintenance and security posture matter. Last release 2017-03-28, minimal adoption, no security disclosure process. In a customer-facing, internet-exposed surface, unmaintained parsers are an input-validation and DoS risk you must own explicitly.
• You need a standard or widely understood dialect. If partners or customers will write filters, align with JSON:API-style filtering, OData $filter, or RQL; ecosystem tools, docs, and SDKs already exist there.
• You need Laravel-native integration. This is a bare parser, not a Laravel package. Expect to write the request binding, authorization/field-level allowlisting, validation, and Eloquent translation yourself — that is where most of the real effort and most of the security risk lives.
• Modern PHP rigor is required. Old code predates current type declarations, static analysis baselines, and PHP 8+ idioms; retrofitting it may cost more than a focused rewrite.
• The filtering is really search. Ranking, typo tolerance, and relevance belong to a search engine (Meilisearch, Typesense, OpenSearch, Algolia), not a filter parser.
• Scale or complexity is high — deeply nested filters, very large user bases, or adversarial input — where you need query-cost limits, depth caps, and timeouts designed in from day one.

How to Pitch It (Stakeholders)

For executives: This is a small, free, public-domain parser that could let customers filter lists and build saved views without us writing a query language from scratch. The catch is that it has been dormant since 2017 and has almost no user base, so the real cost is not the license — it is the engineering ownership, security review, and ongoing maintenance we would assume. Recommendation: treat it as a reference design or a vendored starting point inside a prototype, not as a production dependency we rely on for a customer-facing, revenue-touching feature. If filtering is on the roadmap as a differentiator, budget a short, contained build-or-adopt spike with an explicit owner rather than adopting by default.

For engineering: It gives you a tokenizer/parser you can wrap behind a stable internal interface, with the parsing layer decoupled from query execution. Assume you own it: add input-size and nesting limits, allowlist filterable fields per role, translate the AST to your query builder, and cover it with tests. The Unlicense is permissive and commercially safe, but comes with no warranty and no patent language — fine for internal use, worth a legal glance if embedded in a distributed product. Do not let user-supplied filter strings reach the database unvalidated.