Laravel Dibi Laravel Package

Technical Evaluation

Architecture fit The v1.0.x line materially changes the picture: cuonggt/laravel-dibi is not only a container binding for the Dibi abstraction layer, it ships an operator-facing database dashboard (connection selector, table/index metadata objects, published frontend assets, a JSON contract consumed by a browser UI). Treat it as two products in one package — a data-layer adapter with the same narrow fit as before (legitimate only where Dibi is a house standard or where a Nette/Dibi app is being ported into Laravel), and a database inspection tool with a much broader potential audience. The second half is the interesting one: read-only schema/index browsing is a genuine gap in the Laravel tooling landscape if you do not want to standardise on an external client or a heavier admin panel. The two halves should be evaluated and, if possible, adopted separately — it is entirely reasonable to want the dashboard without committing application queries to Dibi, and vice versa.

Integration feasibility Mechanically still straightforward on Laravel 11+: composer require, php artisan dibi:publish, provider auto-registers via bootstrap/providers.php. The asset story is now clearly load-bearing rather than incidental — the v0.7.0 assessment queried why a database adapter shipped Vite-built assets; v1.0.4 answers that. Those assets render a dashboard, and the release notes reference a "published-asset check" with two distinct error conditions plus a console short-circuit, which implies the package actively validates its published state at runtime or on boot. Confirm what that check does in a production deploy (fail hard? log?) before rollout. Coming from v0.7.0 the upgrade spans an entire major version, so it is not the "patch release, no publish required" path described in these notes — that guidance applies to v1.0.3 → v1.0.4 only.

Technical risk

• Post-1.0 stability is a net positive. The pre-1.0 API-surface risk flagged previously is now largely retired; semver applies, and patch releases are contractual no-breaking-change. This meaningfully de-risks adoption of the data-layer half.
• Maturity signal has reversed. The v0.7.0 assessment read the delayed bootstrap/providers.php fix as evidence of thin install-path testing. v1.0.4 is almost entirely a test-coverage release: dashboard controller, connection-selection endpoint and its JSON contract, published-asset check (including previously-excluded console paths), repository factory error paths, and all three drivers. That is exactly the corrective investment we asked for, and it is the strongest single argument that this package is now safe to depend on.
• The dashboard is an attack surface, and the notes do not address it. A UI that lets a user select a database connection and read schema/index metadata is an administrative capability. Whether its routes are gated by middleware, whether connection selection can reach beyond database.connections, and whether it is registered at all in non-local environments are the questions that will decide if this is adoptable in production. The "selecting a connection the application does not configure is now rejected" fix shows the validation boundary was previously weak — good that it is fixed, but it confirms the surface is real.
• Self-inflicted lockout class. The headline fix describes a remembered connection selection persisting indefinitely and breaking every dashboard request, with the recovery path (the selector) living on the page that no longer rendered. Worth noting the failure shape, not just the fix: state persisted outside the request lifecycle can render the recovery UI unreachable. The remaining exposure is the cache entry itself — the fix discards unusable selections, but a runbook step ("clear the cached connection selection") is still cheap insurance.
• Static Dibi state. The test work mentions resetting Dibi's static state between tests. If Dibi holds connection state statically at runtime, verify behaviour under long-lived workers (Octane, queue workers) where request-scoped assumptions do not hold.
• Vite supply chain remains. No asset changes in this patch, but the JS dependency tree flagged at v0.7.0 persists and will keep generating scanner advisories against a PHP service.
• Niche upstream. Unchanged. Small maintainer base on the package, small and geographically concentrated maintainer group on Dibi. Bus factor still a consideration on both.
• Changelog gap. No prior assessment exists and we have release notes only for v1.0.4. The 0.8 → 1.0.0 breaking-change record is unread; planning an upgrade from 0.7.0 requires reading it.

Key questions

1. Is this being adopted for the data layer, the dashboard, or both? The decision, the risk envelope, and the owner differ in each case.
2. What middleware guards the dashboard routes, can that be overridden in config, and do we intend to expose it in production, staging-only, or behind SSO/VPN?
3. Does connection selection enumerate database.connections only — and are there entries in that array (read replicas, cross-tenant, analytics) we would not want browsable by whoever can reach the route?
4. What does the published-asset check do in a production boot path, and can it be satisfied in CI so a missing publish fails the build rather than a request?
5. What breaking changes landed between v0.7.0 and v1.0.0, and is there an upgrade guide?
6. Does Dibi maintain static connection state at runtime, and is the package safe under Octane / long-lived queue workers?
7. Unchanged from before: what does Dibi give us that Laravel's query builder does not, and do we have an upstream fork/vendoring contingency?

Integration Approach

Stack fit Laravel 11+ remains the floor for the provider auto-registration benefit; the package is now at 1.0.x with a stable API contract. PHP version floor and Dibi upstream constraint still need confirming from composer.json — the release notes do not state either. Teams on Laravel 10 or below remain on an unsupported path.

Migration path

• New adoption: install v1.0.4 directly, php artisan dibi:publish, verify provider registration and asset presence, then confirm dashboard route gating before enabling it anywhere non-local. Wrap any application use of Dibi behind a thin repository layer — less critical at 1.0 than at 0.7, but it keeps the fork contingency bounded.
• Upgrade from v0.6.x/v0.7.0: treat as a major upgrade, not a patch. Assets have changed since v0.7.0 (the "no asset changes since v1.0.3" note is scoped to the last patch), so dibi:publish must be re-run and local customisations diffed and re-applied. Read the 0.8 → 1.0.0 changelog for breaking changes before touching the branch.
• Upgrade from v1.0.3: genuine drop-in. composer update, no publish, no config change. This is the low-risk case and the one the release notes describe.

Compatibility v1.0.4 is source- and asset-compatible with v1.0.3. Relative to v0.7.0, assume breaking changes at the 1.0.0 boundary and asset changes across the 0.7 → 1.0.3 span. Vite toolchain state versus v0.7.0's Vite 8 should be re-checked. Dibi upstream compatibility remains unstated and must be verified.

Sequencing

1. Read the 0.8 → 1.0.0 changelog; extract breaking changes and asset-publish requirements.
2. Confirm PHP floor, Laravel ceiling, and upstream Dibi constraint from composer.json.
3. In a branch, diff currently published Dibi assets before publishing.
4. composer require v1.0.4, re-run dibi:publish, reconcile the asset diff.
5. Verify dashboard route registration and its middleware in a production-like config; decide expose/stage-only/disable and encode that decision in config, not in tribal knowledge.
6. Verify provider binding and asset check on a clean Laravel 11+ skeleton, not just the long-lived local app.
7. Run the Dibi query regression suite; add a smoke test asserting the container binding and a dashboard 200 (or intentional 403) on every deploy target.
8. Staging, then production behind the existing release gate. No cache-clearing step expected given the fix, but confirm a stale connection selection cannot survive the deploy.

Operational Impact

Maintenance Still low-ceremony: small package, terse but honest changelog, now with a test suite that covers the paths that matter. Patch releases are cheap (no publish step at v1.0.4). The recurring costs are unchanged — the Vite dependency tree will keep generating advisories that need triage context, and the Dibi pin needs deliberate review. The new maintenance item is the dashboard itself: it is now a supported internal tool with users, and it needs an owner and a place in the on-call map, not just a composer.json entry.

Support Community-only, no vendor SLA, unchanged upstream bus factor. Internal ownership must be explicit and now covers two surfaces: upgrades to the package/data layer, and operation of the dashboard. Document the Dibi call sites so a fork is bounded work. If the dashboard is adopted, document who is allowed to reach it and how to disable it in an incident.

Scaling Dibi remains a thin PDO wrapper and will not be the bottleneck; ordinary pooling and N+1 discipline still apply, and Dibi still bypasses Eloquent's eager-loading tooling, so explicit query instrumentation is required. Two additions: the dashboard's own queries hit a real database, so point it at a replica or a non-production connection where possible, and the 40%-smaller index payload on every dashboard load is a real improvement on large schemas — worth noting as the reason to take this patch if the dashboard is in use. Dibi's static state is the thing to check before scaling horizontally onto long-lived workers.

Failure modes

• Dashboard lockout: a persisted, unusable connection selection breaking every request, with recovery UI on the broken page. Fixed in this release, but the class remains — keep a cache-clear runbook step.
• Unauthorised schema exposure: dashboard reachable by anyone who can reach the route. Mitigate with middleware and a deliberate exposure decision, reviewed like any admin surface.
• Silent non-registration: the pre-v0.7.0 bug class, still worth a smoke assertion on every deploy target.
• Lost asset customisation: dibi:publish overwriting local edits — relevant when coming from 0.7.x, not on a 1.0.3 → 1.0.4 upgrade.
• Upstream abandonment: unchanged; fork contingency and a documented path back to Laravel's query builder.
• Scanner noise: Vite advisories against a PHP service — unchanged, and now with a UI attached that makes the JS tree less ignorable.

Ramp-up The data-layer half remains low-effort for anyone fluent in SQL and Laravel's container, and the real cost is still conceptual: a written rule for when to use Dibi versus Eloquent, plus half a day of onboarding. The dashboard half is nearly zero ramp-up — that is its appeal — but that is also the trap: a tool that is trivially usable invites use by people who do not know which connection they are pointed at. Brief the team on what the connection selector actually selects. If the team has no Dibi background, still budget time for Dibi's own documentation, which is thin outside Czech-language resources.