Laravel Dibi Laravel Package

Getting Started

Install the package and publish its config and assets:

composer require cuonggt/laravel-dibi
php artisan dibi:publish

The dashboard's connection list is drawn from config/database.php, not from a package-owned connection definition. Dibi connections are ordinary Laravel connections — add or point at one under connections, and it becomes selectable in the UI and usable through the package's repository layer. If you are coming from a 0.6.x/0.7.x install where the connection lived in config/dibi.php, that is the single biggest thing to re-learn.

Where to look first:

1. config/database.php — define the connection(s) you want the dashboard to browse. The selector validates against this array, so anything not listed there is not reachable.
2. The published package config — governs the package itself (dashboard behaviour, asset/asset-check settings) rather than the database credentials.
3. bootstrap/providers.php on Laravel 11+ — provider registration still lives here, not in config/app.php.
4. The published assets directory — the dashboard is asset-backed; the package performs a published-asset check at runtime and raises a distinct error when assets are missing versus stale.

A reasonable first use case: register a legacy or read-heavy database as a normal Laravel connection, browse it in the dashboard during local development, and query it from your own service classes via the package's repository layer instead of modelling the legacy schema in Eloquent.

Implementation Patterns

One connection layer, not two. Add the legacy database to config/database.php alongside your default connection and drive it from .env, exactly as you would any other Laravel connection. Encapsulate queries in a repository or service class; the dashboard is a view onto the same connections your code uses, not a parallel configuration system.

Local-only dashboard. Gate the routes behind APP_DEBUG and non-production, and layer your normal auth middleware on top — it exposes table data and index metadata. Keep staging pointed at a replica so a misconfigured environment can never browse production.

Deliberate connection whitelisting. Because the selector is populated from database.connections, an over-broad config/database.php (analytics, queue, warehouse connections) hands the dashboard more than you intended. Keep sensitive connections out of non-production config files rather than relying on the UI to hide them.

Asset publishing in CI, not by hand. Add php artisan dibi:publish to your post-deploy or container build script and verify it ran — the package's own asset check exists for exactly this failure mode. Note that assets do not change with every release: v1.0.4 explicitly needs no re-publish because nothing changed since v1.0.3. Check release notes rather than blindly republishing.

Upgrade procedure. After composer update cuonggt/laravel-dibi: re-publish only if the release notes say assets changed, then php artisan config:clear. If the dashboard is misbehaving after an upgrade, clear the remembered connection selection (cache) before debugging anything else.

Testing. Use the repository factory against a SQLite or containerised test database and assert on returned rows/metadata directly rather than through Eloquent. Critically, reset Dibi's static state between tests — the package does this in its own suite because connection state otherwise leaks across test cases.

Gotchas and Tips

• Remembered connection selection. The dashboard persists the last selected connection. On versions before 1.0.4, selecting a connection that was later removed from database.connections left every dashboard request returning a 500 with no way back — the selector lives on the page that no longer renders. Clear the cache to recover. 1.0.4 discards an unusable remembered selection, falls back to the first available connection, and rejects such a selection up front; upgrade if you hit this.
• Unsupported drivers fail loudly. The repository factory supports SQLite, MySQL and PostgreSQL; anything else raises an error. Check before wiring up SQL Server or Oracle.
• Dibi keeps static state. This matters beyond tests: under Octane or long-running queue workers, stale connection state can persist between requests and jobs. Reset it explicitly, as the package's own tests now do.
• Index payload contract. TableIndex in 1.0.4 serializes only its mapped fields, no longer emitting both the mapped and raw representation of each index. This cut roughly 40% of the index payload per dashboard load. If you consume the dashboard's JSON yourself, stop reading the raw index shape.
• The published-asset check is real. It distinguishes two different errors (missing vs. mismatched assets) and short-circuits in the console — so a broken publish can still pass a console-based smoke test while the dashboard fails in the browser.
• Two exception families. Dibi's exceptions are not Illuminate\Database\QueryException. Catch the specific type; a broad catch (\Exception) around a repository call also swallows Eloquent failures from the same method.
• Config caching. php artisan config:cache snapshots database.connections as well as the package config, so .env changes to a Dibi-backed connection need a cache clear.
• Extension points. Put customisation in the published config and your own repository/driver classes — never edit files under vendor/, since the next publish overwrites them.
• Debugging a blank dashboard. In order: assets published, assets current, config cache cleared, APP_DEBUG on. It is almost always the first two.