Magic Query Laravel Package

Product Decisions This Supports

• Build vs. buy for dynamic SQL. The core decision this informs is whether to keep hand-rolling query string concatenation for variable predicate sets or adopt a small library that compiles SQL + a parameter bag into a prepared statement. That's a real cost line: every filter-heavy endpoint we ship today re-implements a slice of it.
• Roadmap unlocks. Advanced search, saved filters, admin "report builder" screens, CSV exports, and multi-tenant list views all share the same shape: 0–N user-selected predicates, arrays for IN, optional date ranges. A package like this discounts those epics from "weeks of query-builder plumbing" to "adapter + tests."
• Security posture / risk register. Prepared-statement-by-construction reduces the SQL-injection surface in exactly the places where interpolation tends to creep in (sortable columns, IN lists, optional filters). That's a defensible line item in a security review, not just a dev-experience win.
• Benchmarking a custom builder. Even if we don't adopt, its behavior set — array-to-IN expansion, tuple IN for multi-column matching, conditional/optional predicates — is a useful spec to measure Laravel's whereIn / when() against before we decide to write our own.
• Architecture / reversibility. It is a compiler (SQL text in, SQL text + bound params out), not an ORM. That means it can sit behind a single QueryCompiler interface, which makes "adopt now, swap later" a low-regret decision rather than a lock-in.
• Due diligence caveat for the decision itself: despite being pitched as a Laravel package, it is framework-agnostic PHP from the Mouf ecosystem — no service provider, facade, or Eloquent integration. The decision on the table is "adopt a standalone SQL templating library," not "install a Laravel dependency."

When to Consider This Package

Consider it when:

• You have a genuinely variable predicate set (0–N filters, array params, optional clauses) and are currently concatenating SQL strings to support it.
• You query a legacy schema or read replica where Eloquent/Query Builder is awkward, and raw SQL is already the team's default.
• You need tuple IN / multi-column matching and want it parameterized rather than interpolated.
• You can wrap it in a thin adapter, own the test suite, and pin the version.

Look elsewhere when:

• It's standard CRUD. Laravel's whereIn, when(), and conditional clauses cover the large majority of cases with zero new dependency and zero new concepts.
• You need ecosystem evidence. 20 stars, 0 dependents, single-vendor maintenance is thin signal — treat it as unproven-in-the-wild rather than battle-tested. Active releases (June 2025) mitigate abandonment risk but not bus factor.
• Compliance or audit requires broad adoption or commercial support.
• "Clever" is a liability for your team. Query-rewriting magic is a debugging and onboarding tax; if junior engineers will maintain it, prefer an explicit builder they can read.
• You need ORM features — relations, eager loading, model events, soft deletes — or query introspection beyond text-plus-params.

Net: viable for a bounded, filter-heavy subsystem behind an interface; not viable as a foundation for general data access.

How to Pitch It (Stakeholders)

Executives: "We repeatedly write fragile SQL string-building for filter-heavy screens — search, reporting, exports. This is a small, maintained library that produces safe, parameterized SQL for any number of filters, which cuts both injection risk and delivery time on those features. It's cheap to trial because we'd put it behind an interface, so reversing the decision later is contained."

Engineering: "Framework-agnostic SQL compiler. Input: SQL with named placeholders plus a param bag where values may be arrays or optional. Output: SQL text plus bound params for PDO — giving us IN expansion, tuple IN, and conditional predicates without string concatenation. Not Laravel-native: no service provider, no facade; we'd add a thin adapter over DB::select and own the tests. Adoption signal is low (20 stars, 0 dependents, one vendor), so we gate it behind the interface, run a one-sprint spike on one reporting endpoint, and only broaden if it holds up."