Sql Laravel Package

Technical Evaluation

Architecture fit. psx/sql is a schema-introspection code generator, not an ORM or persistence layer. It reads database metadata (via Doctrine DBAL) and emits PHP classes with typed accessors and column metadata, tied to the PSX framework's own base model/record types. Laravel's persistence path is Eloquent + Query Builder + migrations; there is no Eloquent integration here and none is intended upstream. The realistic fit is therefore narrow and deliberate: generating typed read models / DTOs over a schema we don't own — a legacy database, a read replica, a reporting warehouse, or a third-party system we query directly. It is a dev-time build tool, not a runtime dependency, and should be evaluated as such.

Integration feasibility. Workable, but not drop-in. The generator is CLI-driven, so the natural seam is a thin Artisan wrapper that reads Laravel's config/database.php connections and writes into a git-tracked directory. Three real costs: (1) generated classes may extend PSX base classes, pulling psx/* runtime packages into production unless we template them out; (2) output conventions — namespace, file layout, base class, strictness — won't match our codebase without custom templates or post-generation rewriting; (3) Doctrine DBAL version constraints can collide with Laravel's own DBAL usage, so pinning is mandatory. An engineer can prove or kill this in a day.

Technical risk. High relative to the payoff. 17 stars, 0 dependents, and a sub-0.2 opportunity score mean the package is essentially unvalidated outside its own framework ecosystem, with maintainer concentration and an older PHP/DBAL support envelope. Apache-2.0 is clean legally; abandonment is the actual risk. Runtime risk is near zero because output is plain PHP — all the risk is concentrated in the dev-time generator and its dependency tree, which is a favorable risk shape if we isolate it.

Key questions.

• Does it support custom templates and a configurable namespace/base class — can we emit framework-free DTOs or Eloquent-compatible stubs?
• Which PHP and Doctrine DBAL versions are supported, and does that intersect with our Laravel version?
• How does it handle enums, JSON/JSONB, generated or virtual columns, views, composite primary keys, and unsigned/decimal types?
• Are the PSX runtime packages required at runtime, or can generated classes be decoupled?
• Is there a second maintainer or a documented release cadence? What happens if the repo is archived?
• What do the alternatives produce on our schema — reliese/laravel, kitloong/laravel-migrations-generator, barryvdh/laravel-ide-helper, or ~200 lines of DBAL introspection plus a small template?

Integration Approach

Stack fit. Use it only as a generator for read models in a bounded context. Keep Eloquent as the write/domain path; consume generated types at the edges — API resources, report builders, legacy adapters, import pipelines. Explicitly do not adopt the PSX runtime, its API framework, or its conventions as an application standard.

Migration path (phased, with kill criteria).

1. Spike (≤1 day): install in a scratch branch against a copy of the schema, generate, and measure output — LOC, compile errors, type fidelity versus the migrations. Gate: generated code passes PHPStan at our configured level with no hand-editing.
2. Isolate: put it in a dev-only dependency or a tools/ sub-composer package; emit to app/Generated/; strip or replace any PSX base class so production pulls zero psx/* packages.
3. Wrap: php artisan schema:generate-types --connection=legacy, reading Laravel connection config, writing to a deterministic, git-tracked path.
4. Adopt narrowly: one module behind interfaces, so removal is a delete-directory operation rather than a refactor.

Compatibility. Pin PHP and DBAL versions in CI; verify generated code respects declare(strict_types=1), PSR-4 autoloading, and our static-analysis baseline. Spot-check fidelity: nullable columns must produce nullable hints, DECIMAL must not collapse to float, timestamps must not silently become string, enums must not degrade to string without a documented decision.

Sequencing. This only pays off once migrations are the source of truth. Order: static analysis in CI → spike → wrapper + drift check (generate && git diff --exit-code) → first module → expand module by module. Do not sequence it ahead of static analysis, or the type-safety value is invisible and the tool looks free when it isn't.

Operational Impact

Maintenance. Dev-time only, but generated code is checked in and must be regenerated on every migration touching adopted tables. Budget ~0.5 engineer-day per quarter for version bumps, more if we fork templates — and forking templates is the likely end state, so plan for it rather than resist it. Assign a named owner on the platform team.

Support. Community OSS, single-maintainer concentration, no vendor, no SLA. Our escalation path is "fork it." That is acceptable only because the artifact is replaceable plain PHP; it is not acceptable for anything on a critical path with no exit plan. Write the exit plan down before the first merge.

Scaling. Negligible runtime cost — plain classes, no reflection per request. Generation cost is linear in table count and affects only dev/CI; keep it out of the deploy pipeline and watch memory on very wide schemas.

Failure modes.

• Upstream archived or abandoned mid-adoption.
• A DBAL or PHP major bump breaks introspection or conflicts with Laravel's DBAL pin.
• Silent type drift: a migration adds or retypes a column, nobody regenerates, and the DTO now lies to the compiler — the most dangerous failure because it is invisible until production.
• Generation succeeds but emits code that violates PSR-4 or static analysis, breaking builds unrelated to the change.
• PSX base classes leak into production, expanding maintenance and dependency surface for no product value.
• Schema features (enums, JSONB, generated columns, views, composite keys) are partially supported, producing plausible but wrong types on real code paths.

Ramp-up. ~0.5 day for an engineer to run it and read the output; 2–3 days to build the Artisan wrapper, CI drift check, and template adjustments; 1–2 weeks before a team should trust it inside a production module. Cognitive load for consumers is genuinely low — the output is just typed classes, which is the honest appeal — but the bus factor concentrates entirely on whoever owns the generator configuration.

Verdict. Low-adoption, low-signal tool. Justifiable only as a scoped, isolated, dev-time generator for read-only or legacy schemas, wrapped behind an Artisan command, with a drift check and a written exit plan. Not a foundation for Laravel persistence.