Native Query From File Builder Bundle Laravel Package

Product Decisions This Supports

• Build vs. adopt vs. fork. The package is a thin, narrow utility (load YAML → execute native query). The real decision it forces is whether to take a 0-star, 0-dependent dependency versus writing a ~100-line internal loader you own. That is a procurement/risk call, not a technical one, and it belongs on a PM's desk.
• Where SQL lives in the codebase. It makes "SQL is a first-class, reviewable artifact" an explicit architectural decision: queries move out of Eloquent chains and repository methods into versioned files that diff cleanly in PRs.
• Roadmap for DBA / analyst collaboration. If non-PHP stakeholders (DBAs, data analysts, BI) need to author, review, or tune queries, this pattern makes them contributors instead of ticket-filers. That can unlock reporting and analytics roadmap items that are currently bottlenecked on engineering.
• Feature work it directly enables. Ad-hoc reporting endpoints, admin dashboards, CSV/data exports, cross-database or legacy-DB integrations, and per-tenant/per-region query variants — anywhere hand-tuned SQL beats the ORM and you don't want that SQL smeared across controllers.
• Environment and tenant configurability. Query-from-file naturally supports swapping a query per environment, per country, or per plan tier without a code deploy — a product-flexibility argument for configurable reporting.
• Vendor and OSS risk posture. Choosing this establishes a precedent for accepting single-maintainer, unproven dependencies. That precedent should be a deliberate decision, not an accident.

When to Consider This Package

Adopt (or, more likely, fork) when:

• You have a meaningful, growing volume of hand-written native SQL embedded in PHP, and it is hurting readability, review quality, or testability.
• You want SQL to be code-reviewed and version-controlled as its own artifact — diffs on a query file are far more legible than diffs buried in a builder chain.
• Non-engineers need to read, review, or propose query changes.
• You need the same logical query with environment- or tenant-specific variants.
• You are comfortable wrapping it behind your own small interface so the dependency is swappable.

Look elsewhere when:

• The workload is ordinary CRUD — Eloquent and the query builder are the right answer, and this adds a file-format tax for no gain.
• You need guarantees the package may not provide: parameter binding on every path, connection routing, result caching, query timeouts, or SQL-injection-safe interpolation. Verify before committing; if absent, build the loader yourself.
• Maintainability matters more than novelty. Zero stars, zero dependents, and a single maintainer means the bus factor is one and security patches are not guaranteed.
• Naming diligence: "bundle" is Symfony vocabulary. Confirm there is an actual Laravel service provider, config publishing, and framework-version support before assuming Laravel fit — this may target Symfony and merely be listed as a PHP package.
• Your team already has a convention (.sql files plus a small loader, Doctrine, or a query registry). Adding a second convention costs more than it saves.

How to Pitch It (Stakeholders)

To executives: This is a small open-source utility for moving hard-coded SQL out of application code and into reviewable files. The pattern is sound and commonly valued; the artifact is unproven — zero stars, zero downstream users, one maintainer. Recommendation: do not adopt as a strategic dependency. Instead, run a one-week spike or vendor a minimal internal version (~100 lines) that we control, then revisit. Cost is near zero either way; the risk of a surprise abandonment mid-quarter is the only real downside.

To engineering: Treat this as a reference implementation, not a library. If the pattern fits, copy the idea and own the code — a YAML-fronted query loader with strict parameter binding, a per-environment resolution path, and a cached parse step is a bounded, low-complexity component. If you do take the dependency, pin the version, wrap it behind an internal QueryRepository interface, and add a test that fails loudly if the upstream package changes shape. Check Laravel framework compatibility first — the "bundle" naming suggests Symfony lineage and possibly no Laravel service provider.