Dbal Logger Laravel Package

Product Decisions This Supports

• Framework-upgrade risk planning. Doctrine DBAL 4.x removed the long-standing SQLLogger interface. Any product still relying on it during a DBAL 3 → 4 migration makes a real decision: rewrite query logging in-house, adopt an unmaintained shim, or adopt a small drop-in middleware like this one. This package is the lowest-effort path and directly de-risks that upgrade. Note that the 3.0.0 release adds its own breaking changes (see below), so treat the DBAL upgrade and the middleware upgrade as a single sequenced work item rather than two.
• Observability roadmap for Doctrine-backed services. If a service uses Doctrine (e.g., via laravel-doctrine, or a legacy Symfony/Doctrine codebase inside a Laravel monorepo), this package is a scoped, low-commitment way to restore SQL logging for debugging and profiling without standing up a full APM stack. 3.0.0 strengthens this: stopQuery() now receives the thrown exception, so failed queries can be logged and counted alongside successful ones — useful for failure-rate sanity checks and triage without a full metrics pipeline.
• Build vs. buy for query logging. The scope is narrow (log SQL + params + timing via a DBAL middleware). Building your own is ~a day of work but recurring maintenance. Adopting here is a legitimate "buy" (free, MIT) decision — the real cost is the dependency risk, not the code. The 3.0.0 interface consolidation actually reduces the surface you'd have to shim, since there is now a single DbalLogger contract to wrap instead of two.
• Prioritizing where logging matters. Since it plugs into DBAL's middleware stack, it's usable for targeted enablement (dev/staging only, or a sampled subset of queries in production) rather than blanket instrumentation. That supports a cost-conscious roadmap: log where you need it, mute everywhere else.
• Deprecation/sunset decisions. If a team is still on DBAL 3 and using SQLLogger, this package buys time and unblocks upgrades without a parallel logging subsystem.
• Runtime-baseline decisions. 3.0.0 requires PHP 8.2+ and drops 8.1. If any service in scope is still on PHP 8.1, adopting 3.x forces a PHP upgrade conversation; on 2.x, you stay on an older but functional line. This is a scheduling dependency worth surfacing in the roadmap, not just a technical footnote.

When to Consider This Package

Adopt when:

• You are on Doctrine DBAL 3.x or 4.x and need to replace or retain SQLLogger-style query logging after the DBAL 4 removal.
• You want structured SQL logs (statement, parameters, execution time) for debugging, CI, or performance triage, as a middleware rather than a custom wrapper.
• You want failure visibility as well as success logging — 3.0.0's stopQuery() exception argument lets you record errored queries without bolting on a separate error hook.
• You are migrating DBAL 3 → 4 and want to close the logging gap without writing and maintaining your own middleware.
• You need something small, MIT-licensed, and Laravel/PHP-native that composes with existing DBAL middleware rather than a heavyweight APM product.
• Your logging needs are dev/staging-oriented or sampling-limited, so the blast radius of a small, single-maintainer dependency is acceptable.
• Your services are on PHP 8.2 or newer (required by 3.0.0).

Look elsewhere when:

• Your app is pure Eloquent / Laravel without Doctrine. Laravel's DB::listen, query log, and Telescope already cover this — adding a DBAL middleware is unnecessary surface area.
• You need production-grade observability (dashboards, alerting, sampling, retention, PII scrubbing). Use Telescope, Sentry, OpenTelemetry, or a hosted APM. This package logs queries; it is not an observability platform.
• You require vendor support, SLAs, or a security review cadence. Adoption remains small (low star count, negligible dependents) and effectively single-maintainer, which is a genuine procurement blocker for regulated or enterprise contexts.
• You need profiling beyond logging (slow-query analysis, N+1 detection, flame graphs). Pair with dedicated tooling.
• You are on DBAL 2.x or a very old stack — the middleware API won't match, and the upgrade path is a different problem.
• You are pinned to PHP 8.1 or older — 3.x is closed to you; either stay on 2.x with a documented freeze or upgrade PHP first.

Adoption guardrails: pin the version, wrap it behind your own logging interface so it can be swapped, and confirm the maintainer's release/response cadence before relying on it in anything beyond dev/staging. If upgrading from 2.x, budget for the 3.0.0 breaking changes: PHP 8.2+ baseline, QueryLogger/DbalLogger merged into a single DbalLogger interface, added native type declarations on all interface methods, and an updated stopQuery() signature that now takes the exception. Any custom logger implementations must be updated in lockstep; check UPGRADING.md and lean on static analysis in CI to catch signature drift.

How to Pitch It (Stakeholders)

For executives: "We have a narrow, low-cost dependency choice that removes a known blocker in our database-layer upgrade. Doctrine's SQL logger was removed in a major version, and this small MIT-licensed package restores that capability as a drop-in middleware. It's free, scoped, and reversible — the risk is supplier concentration (one maintainer, minimal adoption), so we recommend restricting it to non-production environments and wrapping it behind our own interface. The new 3.0.0 release is actively maintained: it modernizes the interface, adds error-path logging, and drops end-of-life PHP 8.1. That activity is reassuring, but it also means a one-time upgrade cost and a PHP 8.2 minimum for the services that adopt it. Net effect: we unblock an upgrade without funding an in-house logging component."

For engineering leadership:

• Problem it solves: SQLLogger was removed in DBAL 4. Teams on Doctrine need a logging replacement or a custom wrapper.
• What we get: a DBAL middleware that captures SQL statements, bound parameters, and timing — the same debugging value, composable with existing middleware. 3.0.0 adds exception-aware stopQuery(), so failed queries are loggable too, and consolidates the two logger interfaces into one simpler contract.
• Cost: zero license cost; small integration effort; one dependency to track. 3.0.0 is a breaking release — merging QueryLogger/DbalLogger, adding native types, and requiring PHP 8.2+ — so plan a short migration window rather than a silent composer update.
• Risks: low adoption, single-maintainer exposure, no support contract, and a PHP 8.2 floor that may outpace some services. Mitigate by pinning the version, isolating it behind an internal logging abstraction, gating adoption on PHP 8.2 readiness, and limiting to dev/staging initially.
• Alternatives considered: in-house middleware (maintenance overhead), Laravel Telescope/DB::listen (doesn't cover Doctrine paths), APM vendors (heavier, costly, overkill for this need).
• Recommendation: Trial in dev/staging during the DBAL upgrade, on PHP 8.2+ services only; promote to production only with a wrap-and-pin plan and a named internal owner. Treat the 2.x → 3.x jump as a deliberate change with a reviewable diff, not an incidental bump.