Query Parser Laravel Package

Technical Evaluation

Architecture fit. Unchanged in shape: gdbots/query-parser remains a stateless tokenizer that converts a raw search string into structured nodes, and it still belongs behind an adapter between the HTTP layer and the search backend. The v3.0.0 enum change does, however, tell us something concrete about the output model: node types are now expressed as native PHP enums rather than home-grown enum classes. That is architecturally better for us — native enums are a language primitive, trivially mapped into our own DTOs, and far less likely to drag gdbots' message infrastructure into our domain. It is also more rigid: a PHP enum is a closed set. If the node/operator taxonomy is enum-backed, we cannot subclass or extend it to add field:value, negation, or ranges — that path now definitively runs through a fork.

Integration feasibility. Materially improved. The single largest prior blocker was that a 2021 release might declare ^7.x and never have been exercised on PHP 8. v3.0.0 requires PHP 8.1, which sits at or below the floor of our target matrix (Laravel 10 on 8.1, Laravel 11 on 8.2, running 8.2–8.4). That converts a likely hard stop into a routine composer require. Two unknowns remain: the release notes are silent on transitive dependencies, so we still must confirm whether gdbots/pbj and any Symfony pins are in the tree, and silence on PHP 8.4/8.5 means the floor is declared but the ceiling is untested.

Technical risk. The lifecycle risk profile has shifted rather than disappeared. Positives: a major version with an explicit breaking-change list is evidence of semver discipline and active stewardship, and modernizing the PHP floor and adopting native enums is exactly the maintenance work an abandoned package does not get. Negatives: this is a single-org project with a three-year gap preceding it, one release does not establish a cadence, and a brand-new major typically has near-zero production adoption — we would be an early v3 consumer. The prior scoring signal (0.76 quality, opportunity 28.17) was computed against the 2021 artifact and should be treated as stale until re-run. Specific items to verify:

• Whether gdbots/pbj (or any gdbots message layer) is still a required dependency in v3, or whether the enum switch was partly a move away from it.
• Whether the node-type/operator set is enum-backed and therefore closed to extension without forking.
• CI matrix coverage for PHP 8.3/8.4, and whether 8.5 is on their roadmap.
• Whether enum cases are backed (string/int) and stable — this determines serialization behavior and cache safety.
• Robustness on adversarial input, unchanged from before: regex-based tokenizers are prone to backtracking blowups on long or pathological strings.

Key questions.

1. Does v3.0.0 resolve cleanly on Laravel 10/11 (PHP 8.2–8.4) without --ignore-platform-reqs, and is gdbots/pbj still in the graph?
2. Is the enum set closed, and does adding our own operators require a fork rather than an extension point?
3. Are enum cases backed with stable values we can safely serialize into a parse cache?
4. Is there any documented release cadence or CI evidence for 8.4+, or was v3.0.0 a one-off modernization?
5. Does a ~100-line owned tokenizer remain the cheaper answer if we need only whitespace and quoted-phrase splitting?

Integration Approach

Stack fit. Unchanged and still engine-agnostic: parse once into a canonical representation, compile per backend. The enum output makes the "map immediately into our DTOs" step more mechanical than before, which is a genuine reduction in adapter effort. The over-scoping concern (hashtags, mentions, operators we may never use) still stands and is now slightly sharper, since an unused closed enum set is dead weight we cannot trim without forking.

Migration path. Same pattern, with the version pinned deliberately: bind a QueryParser contract in our namespace exposing parse(string): ParsedQuery, and map vendor enums to our own string-backed values at the boundary. Never type-hint vendor enum cases in controllers, form requests, jobs, or cache payloads. If any earlier evaluation touched 2.x, discard it — the enum change means 2.x and 3.x mapping code is not portable, and carrying both is not worth it.

Compatibility. Re-run the dependency spike against v3 specifically; the previous spike's result is invalidated by the PHP floor change and the enum refactor. Use composer why-not against the real Laravel skeleton. The declared PHP 8.1 floor is not a forward-testing signal — 8.1 has left active support — so add an explicit CI job on 8.3 and 8.4 and treat 8.5 as a known-untested edge. Apache-2.0 licensing is unchanged, so vendoring or forking remains legally cheap and is now the more likely endgame given the closed enum set.

Sequencing.

1. Dependency spike against v3.0.0 on the actual Laravel version — half a day, go/no-go, explicitly checking for gdbots/pbj and Symfony pins.
2. Contract + adapter + DTO mapping, with vendor enums converted at the boundary.
3. Characterization tests: golden files over realistic queries (unicode, emoji, escaped quotes, max-length strings), including the serialized form of mapped node types so enum-value drift is caught.
4. Feature-flagged wiring into the search path with shadow comparison against current behavior.
5. Move the fork-vs-replace decision earlier than six months. Because the enum taxonomy is closed, assume fork is the answer if we need any operator the package does not ship.

Operational Impact

Maintenance. Improved but still assume we own it. The v3.0.0 release is real evidence that someone is paying attention; it is not evidence of a predictable cadence after a multi-year gap. Keep the recurring line item — annual PHP compatibility check plus a documented fork procedure — and re-evaluate cadence at the next release. A named owner is still mandatory. Forking remains legally trivial under Apache-2.0, which is what makes the irregular cadence tolerable.

Support. Unchanged: no commercial support, no SLA, no security advisory channel beyond GitHub. Pin the exact version (3.0.0, not ^3.0) in composer.lock and lean on automated dependency scanning of the transitive tree. Blast radius stays at one adapter class.

Scaling. Negligible, as before — pure CPU, microseconds, no I/O, no shared state, scales with the web tier. One new caveat introduced by the enum change: if we memoize parse results, the cache key and serialized value must be our representation, not the vendor enum, or a future enum-case rename silently invalidates cached payloads.

Failure modes.

• Enum case rename or reordering in a later 3.x: breaks mapping code or cached payloads. Mitigated by pinning the exact version and asserting on serialized output in golden files.
• Closed taxonomy: we need an operator the enum does not cover and cannot subclass — fork under our namespace. Highest-likelihood structural failure now.
• Pathological input: enforce a hard query-length cap (512–1024 chars) before parsing and degrade to naive splitting on exception.
• Unicode/encoding: hashtags and mentions remain the weak spot for multi-byte and emoji input; cover explicitly.
• Unproven on 8.4/8.5: the declared floor is 8.1; a Laravel major or PHP minor that pulls newer Symfony could still collide, and that blocks our upgrade path. Pre-emptive fork once the dependency proves load-bearing.
• Output-model coupling: if any vendor node or enum escapes the adapter, a swap becomes a refactor rather than a class replacement.
• Early-adopter risk: a fresh major with low adoption may ship regressions that a mature 2.x would not have. Version pinning plus golden files contain this.

Ramp-up. Low and slightly better than before — the enum surface is smaller and more legible than hand-rolled enum classes, though still sparsely documented, so expect to read source for exact token boundaries and case semantics. Roughly a day to productivity, two to three days to production-grade integration including the adapter and test corpus. Net TPM position: v3.0.0 clears the PHP-version objection that dominated the prior assessment and improves the output model, so adopt behind a strict adapter on a pinned version — but plan on forking rather than extending, and re-check maintenance cadence at the next release before treating this as a durable dependency.