Query Builder Laravel Package

Technical Evaluation

Architecture fit. makinacorpus/query-builder is a standalone, driver-agnostic SQL builder: queries are expressed as structured data (selects, joins, where clauses) and compiled to a dialect-specific SQL string. This is conceptually adjacent to — not a replacement for — Laravel's Illuminate\Database\Query\Builder and Eloquent. The only defensible fit inside a Laravel codebase is as a query-definition/serialization layer (e.g. saved reports, user-defined filters, query templates persisted as JSON) that compiles to SQL and hands off to Laravel's connection for execution. Using it as the primary data-access layer would create a second, parallel query abstraction alongside Eloquent, doubling the mental model for every developer on the team.

Integration feasibility. Technically low-friction: MIT-licensed, Composer-installable, no framework coupling implied, and usable as a leaf dependency behind an internal adapter. Practically, expect to write the Laravel glue yourself — there is no evidence of a service provider, facade, config publishing, or Laravel version constraints. Execution, connection pooling, transactions, logging, and query timing all remain Laravel's responsibility.

Technical risk. High relative to value:

• Adoption risk. 7 stars and 0 dependents means effectively no third-party validation. There is no ecosystem to catch regressions, no Stack Overflow corpus, and no hiring pool that knows the API.
• Bus-factor risk. Single-organisation ownership (Makina Corpus, a French agency) with no evidence of a public roadmap, security policy, or multi-maintainer governance.
• Security surface. A builder that emits raw SQL must bind parameters, not interpolate values, and must correctly quote identifiers across dialects. This needs explicit verification before any production use; identifier handling is the classic injection vector in third-party builders.
• Dialect drift. A driver-agnostic abstraction lags native grammars. Expect gaps on CTEs, window functions, JSONB operators, LATERAL joins, and upserts — precisely the features reporting queries tend to need.
• Silent divergence. If some queries go through this builder and others through Eloquent, you get two grammars, two escaping behaviours, and two debugging stories.

Key questions.

1. What is the last commit date, release cadence, and open-issue resolution rate? Is there a tagged stable release or only dev-main?
2. Does it use bound parameters end-to-end, and how are identifiers/aliases escaped per dialect?
3. Which dialects are actually implemented and tested (MySQL, PostgreSQL, SQLite, SQL Server)?
4. What PHP versions and Laravel versions are supported by composer.json constraints?
5. Is there test coverage and CI? What is the coverage of the compilation layer?
6. Does it support CTEs, window functions, and subqueries — or would we be extending it ourselves?
7. Is Makina Corpus willing to commit to maintenance, or are we implicitly forking?
8. What is the concrete capability we cannot get from Laravel's builder plus a small query-DTO of our own?

Integration Approach

Stack fit. Poor as a core ORM replacement, acceptable as a narrow component. The natural boundary is: our application owns the query model (a validated DTO), this package owns compilation, and Laravel's DB facade owns execution. Do not let it manage connections, transactions, or result hydration.

Migration path. There is no migration — nothing depends on it today, so this is greenfield adoption, not a swap. Recommended path:

1. Spike (1–2 weeks). Build three real reporting queries from the backlog through the package, including one with joins and aggregates. Benchmark against hand-written Laravel builder equivalents for correctness, readability, and LOC delta.
2. Adapter layer. Wrap the package behind an internal QueryCompiler interface with compile(QueryDefinition): array{sql, bindings}. No application code imports the vendor namespace directly. This makes the package swappable — a fork, a replacement, or a return to Laravel's builder — without touching call sites.
3. Feature-flagged rollout scoped to one non-critical reporting surface.
4. Decision gate. Promote to wider use only if the spike shows a clear LOC/maintenance win over a hand-rolled DTO + Laravel builder.

Compatibility. Verify PSR-4 autoloading, PHP constraint, and absence of conflicting transitive dependencies before locking. Register it as a singleton in a service provider we own; do not rely on package discovery. Pin the version exactly (composer require with a fixed constraint) and commit composer.lock — with 0 dependents, semver discipline is unproven and a minor bump could break compilation output.

Sequencing. Security review of escaping/binding → spike → adapter interface → single-surface pilot → evaluate → fork-or-adopt decision. Front-load the security review; it is the only step that can kill the initiative outright.

Operational Impact

Maintenance. Assume we own it. Budget for periodic fork-and-patch, dependency-bump verification, and dialect updates when we upgrade PostgreSQL or MySQL. With one small team and no upstream SLA, this is a recurring, unbounded line item — modest in absolute terms but non-zero forever.

Support. No commercial support, no vendor contact path, no defined security disclosure process. Internal knowledge will concentrate in whoever runs the spike. Mitigate with an ADR, a short internal README, and the adapter interface so the package is not load-bearing for architecture.

Scaling. Negligible runtime footprint — compilation is in-process string assembly, dwarfed by database execution time. The scaling concern is organisational, not technical: the abstraction will resist supporting new database features, and every new dialect need becomes our problem.

Failure modes.

• Injection via mis-escaped identifiers or unbound literals — highest severity, mitigated only by review and a binding-focused test suite.
• Dialect drift — generated SQL is valid for the tested engine but breaks on upgrade or on a secondary engine.
• Abandonment — upstream goes quiet; we are pinned to an unmaintained dependency with a known-CVE risk profile.
• Abstraction leakage — teams bypass the adapter and call the vendor API directly, defeating swappability.
• Silent wrong results — a bug in clause composition produces syntactically valid but semantically incorrect SQL, which is worse than an error. Requires golden-file tests comparing compiled output to expected SQL.

Ramp-up. The API surface is small; a mid-level PHP developer should be productive in 2–3 days. The real ramp-up cost is the conceptual one: teaching the team when to use this builder versus Eloquent, and why two query layers exist. That ambiguity is a persistent tax on onboarding and code review unless the boundary is documented and enforced by the adapter interface.

Recommendation. Proceed to a time-boxed spike only, gated on the security review and a demonstrated win over a ~200-line in-house query DTO plus Laravel's builder. Given 7 stars, 0 dependents, and a single-organisation maintainer, this should not become a platform dependency without a credible fork-and-own commitment.