Product Decisions This Supports
- Legacy modernization scope and sequencing. A SQL→Laravel builder converter is an effort estimation instrument as much as a tool. Running it against a representative sample of our raw
DB::select() / string-concatenated queries gives a defensible coverage percentage ("we can auto-convert ~X% of N queries"), which converts a vague "migrate off raw SQL" epic into a sized, phase-able roadmap item with a measurable exit criterion.
- Build vs. buy vs. fork for internal migration tooling. The hard part of any legacy-to-Laravel effort is the SQL parse → builder-emit layer. This package is MIT-licensed and small (186 stars, single-author, last release Nov 2021), so the right decision frame is fork and vendor it as an internal codemod, not adopt it as a dependency. That decision (fork vs. write from scratch) is worth roughly weeks of engineering; this package is the cheap option to evaluate first.
- Developer-tooling investment. Positions a migration-assistant CLI as an internal DX product with its own success metrics: conversion coverage on our corpus, manual-fix rate per converted query, engineer-hours saved per 100 queries.
- Feature ideation with a hard guardrail. It superficially enables "let admins paste SQL and we run it" or "SQL import for reporting config." Those are not supported by this package — converting SQL text into a builder is a translation convenience, not a sanitization or authorization boundary. Any roadmap item that treats it as a security layer should be killed at review.
- Deprioritization candidate. If we're not actively migrating a PHP codebase, this has no roadmap pull. It's a one-time migration accelerant, not a platform capability, and the 2021 last-release date means we own any fork indefinitely.
When to Consider This Package
Consider it when:
- We have a bounded, known corpus of SELECT-style SQL (joins, where clauses, group by / having, basic aggregates) inside a legacy PHP app and a funded migration to Laravel.
- The use case is a one-off codemod or internal CLI tool, where imperfect output is caught by tests and reviewed by an engineer — not a runtime code path.
- We want a reference implementation to study before writing our own parser, or to fork outright under MIT.
- We need migration-effort instrumentation — even partial conversion success is useful as a metric of how tangled our SQL debt is.
- Complex constructs (CTEs, window functions, stored procedures, vendor-specific syntax) are rare or can be flagged for manual rewrite.
Look elsewhere (or don't adopt) when:
- It would be a production runtime dependency. Last release 2021, small maintainer base, no published support matrix for current Laravel/PHP versions — assume it needs framework-compatibility work before it even runs.
- We need writes (INSERT/UPDATE/DELETE) or DDL converted; this is a query-side tool.
- The real need is the inverse (builder → SQL) for logging/debugging — Laravel ships
toSql() and dd(); buy nothing.
- The need is query analysis, linting, or performance review — that's a different tool category entirely.
- The SQL is user-supplied at runtime. Never treat translation as a security control.
Gate before adoption: a 1–2 day spike running it over ~50 real queries from our codebase. Kill it if coverage is low or setup cost exceeds the manual-rewrite baseline.
How to Pitch It (Stakeholders)
To executives: This is a small, free (MIT) utility that translates raw SQL into Laravel's native query-builder syntax. Its value is not as a product dependency — it's as a measuring stick and head start for our legacy-PHP-to-Laravel migration. For roughly two engineer-days, we can run it against our existing SQL and come back with a hard number: what share of our database code can be converted automatically versus hand-rewritten. That turns a "someday we should modernize" line item into a costed, defensible plan. Risk is low because we'd fork it internally rather than depend on the upstream project, which has been dormant since 2021. Recommendation: approve the spike, not the adoption.
To engineering: It gives us the SQL-parse → builder-emit layer we'd otherwise spend weeks building, under a permissive license. Treat upstream as a starting point: fork it, pin it, add our own tests, and own the maintenance. Validate against our real query corpus and current framework version first — expect compatibility work. It converts reads, not writes, and it is absolutely not a sanitizer; any user-supplied SQL still needs its own controls. If the spike shows poor coverage on our actual SQL, the fallback cost is two days, and we'll have learned exactly where the messy queries live.