Native Query From File Builder Bundle Laravel Package

Technical Evaluation

Architecture fit

The first finding is a naming/ecosystem mismatch: micayael/native-query-from-file-builder-bundle is packaged as a Symfony bundle, not a Laravel package. There is no composer.json extra.laravel provider entry, no Illuminate\Support\ServiceProvider, and no Laravel-facing facade implied by the name. Laravel's container and package discovery model differs materially from Symfony's Bundle → Extension → Configuration → compiler-pass pipeline. Any adoption in a Laravel codebase therefore requires a translation layer we own, not an install-and-go integration.

Functionally, the capability it targets is legitimate and recurring: externalizing native SQL out of PHP into YAML files so it can be versioned, reviewed, and edited by people who are not PHP developers. This is a real pain point in reporting, analytics, and legacy-database access layers where Eloquent/Query Builder is a poor fit.

Integration feasibility

Feasible but non-trivial. Three concrete gaps:

• Bundle lifecycle: we would need a ServiceProvider that manually instantiates the bundle's query registry/builder, wires the YAML file paths, and binds it as a singleton. We lose Symfony's compiler-pass-driven configuration and must reimplement config validation.
• Database abstraction: this family of packages typically builds on doctrine/dbal. Laravel ships Illuminate\Database over PDO. Bridging means either (a) adding DBAL as a parallel connection stack — two connection pools, two transaction contexts, a real correctness hazard — or (b) replacing the DBAL executor with an adapter over DB::connection()->select() while retaining the YAML parsing/binding layer.
• Dependency surface: YAML parsing relies on symfony/yaml, which is present in most Laravel installs but not guaranteed in slimmed images; version constraints from a 0-star package may pin Symfony components below what the Laravel version requires.

The realistic outcome is a fork or a thin internal wrapper, not a dependency we consume upstream.

Technical risk

The package's opportunity score (26) and zero adoption corroborate a "do not adopt directly into a production path" conclusion without a spike.

Key questions

1. Does it support named parameters, typed binding, and array/IN expansion — or does it interpolate values into SQL strings?
2. Who maintains it, what is the release cadence, and is there CI?
3. Which DBAL/Symfony versions are constrained, and do they conflict with our Laravel + PHP matrix?
4. Does it support multiple connections, read replicas, and participation in an existing transaction?
5. What is the hydration contract — arrays, objects, scalars, or DBAL statements?
6. Is parsed YAML cached, or is the filesystem hit on every query?

Integration Approach

Stack fit

Poor as a drop-in; moderate as a pattern donor. The correct framing for stakeholders: we are evaluating whether to reimplement a ~150–250 LOC internal service (SqlFileRepository + YamlSqlLoader + NamedQueryExecutor over DB::connection()->select()) inspired by this package, rather than to take a Symfony bundle into a Laravel application. That reframing eliminates the bundle-lifecycle gap, the DBAL dual-stack risk, and the upstream maintenance risk in one move.

Migration path

If we proceed with the package as a reference implementation:

1. Spike (2–3 days) — install in a scratch Laravel app, write a provider shim, execute three representative queries (simple select, parameterized IN, multi-join report) against a disposable schema.
2. Audit — read the executor for binding correctness and confirm no string interpolation of user input.
3. Decide — fork-and-pin vs. build-internally. Given the maturity signal, build-internally is the likely landing zone; the fork only wins if the YAML DSL is richer than we'd write ourselves.
4. Pilot — one non-critical reporting endpoint, behind a feature flag, with the SQL files under code review like any other source file.

Compatibility

Requires validation against our PHP version, Laravel major, and doctrine/dbal if any other dependency already pulls it. Watch for symfony/yaml constraint conflicts. The shim should be written against interfaces we define, not the bundle's concrete classes, so a later swap is cheap.

Sequencing

Spike → security/binding audit → build-vs-fork decision → internal abstraction → single pilot → measure (query authoring turnaround, defect rate, p95 latency) → broaden or retire. Do not sequence this before the binding audit; SQL execution is not a place to discover semantics in production.

Operational Impact

Maintenance

The dominant ongoing cost is not the code — it is the new artifact class: .yaml files containing production SQL. That means ownership rules (who may edit, who reviews), a directory convention, a linting step, and a deployment story. SQL in YAML is invisible to PHP static analysis, IDE navigation, and most SAST tooling; we would be trading ORM friction for a blind spot unless we add review discipline up front. If we build internally we own ~200 lines; if we fork we inherit periodic upstream-merge work on an unmaintained repo.

Support

MIT, no vendor, no SLA, no maintainer responsiveness demonstrated (0 stars / 0 dependents). Support is entirely internal. That is acceptable for a thin internal utility and unacceptable as an unexamined third-party execution path for SQL.

Scaling

Two concerns. First, I/O and parse cost: if YAML is re-read and re-parsed per query, high-QPS endpoints pay a filesystem tax; a parsed-query cache keyed by file mtime must be mandatory. Second, connection topology: without first-class multi-connection and replica support, this becomes a single-connection path that cannot route reads to replicas — a real ceiling for reporting workloads that are exactly the ones this pattern targets.

Failure modes

• Missing or renamed YAML key → runtime exception at query time, not startup; needs a boot-time validation pass over all query files.
• Malformed YAML → opaque parse error; wrap with file-path context.
• Parameter name mismatch between caller and YAML → silently wrong result set or an empty result, the most dangerous failure here.
• Unbound parameter interpolated into SQL → injection.
• Unvalidated multi-statement SQL in YAML → a query file becomes an arbitrary-DDL vector.
• Deploy-time drift: file changed but cache not cleared → old SQL executed silently. Tie cache invalidation to deploy, and log the resolved file path + hash per execution.

Ramp-up

Low for engineers comfortable with SQL and Laravel's DB facade; the YAML DSL is small. The genuine learning curve is organizational, not technical: teaching the team that a data file now carries production behavior and deserves the same review rigor as a migration. Budget roughly a sprint for pilot + documentation + review conventions, and treat the upstream package as reference material rather than a dependency we promise to keep current.