Dibi Laravel Package

Technical Evaluation

Architecture fit. cuonggt/laravel-dibi remains an adapter rather than a replacement ORM — service provider, facade, and a bridge at Laravel's connection layer so Dibi's Fluent builder runs alongside Eloquent and the native query builder. What the v1.0.4 notes reveal that the v0.7.0 assessment could not see is the package's second surface: it ships an operator-facing database dashboard (connection selector, table metadata, index browsing) with its own JSON contract to a frontend and its own persistence of the selected connection. That is materially more than a driver shim. The architecture fit is now two-part: driver (unchanged — highest value where the team has Dibi fluency; low value greenfield) and dashboard (highest value as a read-only schema/inspection tool for teams already on Dibi; irrelevant and arguably unwanted for teams that only want the query builder).

Integration feasibility. Mechanically still cheap — Composer, publish, select the driver. The upgrade story for this release is unusually clean: patch-level, no breaking changes, and explicitly no dibi:publish required because assets are unchanged since v1.0.3. The caveat is that we are jumping from an assessed v0.7.0 straight to v1.0.4. At least three releases we have never reviewed sit in between, including a major version boundary whose breaking changes, config additions, route registrations, and middleware expectations were never assessed. The v1.0.4 fixes read as mature maintenance — self-healing from poisoned state, payload deduplication, and closing genuinely embarrassing test gaps (the published-asset check's console short-circuit had kept an entire error path out of the suite) — which is a positive quality signal, but it is a signal about v1.0.4, not about the upgrade path to reach it.

Technical risk. Four areas:

• Unreviewed major-version transition. The 0.x→1.0 surface is the single largest unknown. Semver discipline now protects us going forward, which retires the old "pin exactly, minors may shift behaviour" warning — but only after the v1.0.0 breaking changes are read and mapped.
• Statefulness and self-recovery. The headline fix describes a remembered connection selection persisted across requests that, once invalid, bricked every dashboard request with no in-product escape. Good that it's fixed and good that the selection is now validated against database.connections. But the class of bug — request-affecting state held outside the request, with no recovery path — is exactly the kind of thing that recurs. It also raises an Octane/long-running-worker question: the same notes mention resetting Dibi's static state between tests, which implies global state that a persistent worker would carry across requests.
• Dashboard as an attack and disclosure surface. A connection-selection endpoint that previously accepted arbitrary connection names, plus schema/table/index metadata rendered to a browser, is a privileged surface. Validation of the connection name closes the obvious hole; authorization, route exposure, and whether it can be enabled in production remain open.
• Observability gap (unchanged). Dibi manages its own connections rather than routing through Laravel's PDO layer, so Dibi traffic stays largely invisible to DB::listen, Telescope's query tab, and PDO-based APM. Architectural, not a defect, but still an explicit accepted trade-off — and now it also means the dashboard's own queries are outside your usual instrumentation.

Key questions.

1. What changed in v1.0.0–v1.0.3? Produce the breaking-change list, new config keys, and any route/middleware registration introduced between v0.7.0 and v1.0.4.
2. Is the dashboard opt-in? Which routes does it register, under what middleware (auth, authorization, environment gating), and can it be fully disabled in production?
3. Where is the remembered connection selection stored — session, cache, cookie — and is it scoped per user? The v1.0.4 bug implies shared or long-lived storage.
4. Does Dibi's static state leak across requests under Laravel Octane or any long-running worker? What resets it in production?
5. What is the tested matrix now across Laravel 11/12/13 and PHP 8.2–8.5, and are all three drivers (the notes confirm MySQL/Postgres/SQLite coverage) exercised in CI on each?
6. Does the driver honour Laravel semantics we depend on — nested transactions/savepoints, DB::transaction retries, read/write splitting?
7. Is Dibi intended for migrations and writes, or read/query paths only? Mixing write paths across two abstractions in one request remains the sharpest correctness hazard.
8. Bus factor: still a single-maintainer package on a single-maintainer upstream. Is there an internal fork/vendoring plan?

Integration Approach

Stack fit. Unchanged: PHP 8.x on Laravel 11–13 via Composer with auto-discovery plus the explicit bootstrap/providers.php entry. No infrastructure or sidecar. New consideration: the dashboard is a web surface inside your app — it inherits your auth stack, your route table, and your middleware ordering, and must be placed deliberately rather than absorbed by auto-discovery.

Migration path. For v1.0.3 → v1.0.4: trivial. Patch-level, no config or asset changes, no republish. The real work is v0.7.0 → v1.0.4, which is a two-hop migration: read the v1.0.0 release notes and any UPGRADE guide first, then walk v1.0.1–v1.0.4 as patches. Budget for one breaking-change review, not a version bump. Pin to ^1.0 once validated so future patches arrive without ceremony.

Compatibility. Confirm the pinned upstream Dibi version against what 1.x expects — the 0.x→1.x jump may have moved that constraint. Re-run your own CI matrix rather than trusting the changelog; the added test coverage is a strong signal but it is the maintainer's matrix, not yours. Teams still on Laravel 10 or earlier remain out of scope for the provider-registration fix and should plan that skeleton upgrade separately.

Sequencing.

1. Read v1.0.0–v1.0.3 notes; write down breaking changes, new config keys, and route/middleware additions.
2. Spike branch: install v1.0.4, publish, diff config and route table against current state.
3. Prove one read path and one transactional write path end-to-end against a real database.
4. Exercise the dashboard deliberately: confirm auth/authorization, confirm the connection selector rejects unconfigured names, and confirm a poisoned selection cannot brick the page.
5. If on Octane or any persistent worker, run a soak test for static-state and remembered-selection bleed.
6. Confirm how (or whether) Dibi queries surface in logging/APM; decide the compensating control.
7. Staging canary for one service, one release cycle, then roll out per service.

Operational Impact

Maintenance. Steady-state cost is still low, and the 1.0 milestone improves it: semver discipline replaces the quarterly pre-1.0 audit, and patch releases become routine. Two things are added to the runbook. First, the dashboard is now a feature you own — its access control, its route exposure, and its behaviour after data/config changes are yours to test, not the package's. Second, keep the published-asset check visible: it now has test coverage upstream, but the runbook step and the "skipped silently, breaks the debug panel" failure mode are unchanged for any future release that does touch assets.

Support. No vendor SLA; GitHub issues plus internal ownership. The named steward requirement is now sharper because the blast radius is larger — a broken driver is a query problem, a broken dashboard was, until this release, an unrecoverable page with no self-service fix. Assign the same owning team the dashboard's access model as well as the driver.

Scaling. Connection behaviour, pooling, and replica logic remain Dibi's; evaluate against Dibi's model, not your Laravel tuning. The dashboard adds a distinct scaling concern: schema introspection over large databases, cached connection state, and index metadata payloads. The ~40% index-payload reduction is a real win precisely because that payload scales with index count on every dashboard load — but it is a symptom that metadata volume is a live cost, so test against your largest schema, not a demo database.

Failure modes.

• Poisoned persisted state — the v1.0.4 bug class: an unusable remembered value survived indefinitely and failed every subsequent request with no UI path to recovery. Fixed here and now validated at the point of selection, but design review should assume this pattern can recur anywhere the package persists state.
• Unauthorized dashboard exposure — schema, table, and index metadata reachable beyond the intended audience if routes register without the middleware you assumed.
• Transaction divergence — Dibi and Eloquent writing in the same request with independent transaction scopes; still the highest-severity correctness risk.
• Observability blind spot — a slice of database traffic never reaches your dashboards, extending incident diagnosis.
• Stale published assets — unchanged for asset-bearing releases; unchanged mitigation.

Ramp-up. Low for engineers comfortable with SQL, and now broader than engineering: the dashboard is legible to analysts and support staff, which is a benefit and a governance obligation — those users need the access model explained, not just the query builder. The real cost remains dual-API cognitive load: knowing when to reach for Eloquent versus Dibi, and enforcing it in review. A one-page convention doc plus a code-review rule covers most of it; roughly a sprint of familiarisation before the first production service, less for teams with existing Dibi experience. Add a short section on the dashboard's intended audience and access rules.

Bottom line. v1.0.4 is an excellent patch — it repairs an unrecoverable-state bug, closes a connection-validation gap, removes real payload waste, and completes driver-level test coverage including paths that had quietly fallen out of the suite. It also tells us the package has grown a user-facing dashboard and crossed 1.0 since we last assessed it, and that is the substantive update: semver stability is now a genuine benefit, the pre-1.0 version-discipline condition is retired, and two new conditions take its place — review the unreviewed v1.0.0–v1.0.3 transition, and treat the dashboard as a privileged surface with an explicit access model. The adoption calculus otherwise holds: a good, low-ceremony fit for teams with a Dibi footprint, with transaction divergence and the observability gap as the standing trade-offs to accept explicitly.