Dbal Logger Laravel Package

Technical Evaluation

What it actually is. firehed/dbal-logger remains a framework-agnostic Doctrine DBAL middleware, not a Laravel package. It re-implements the removed SQLLogger as DBAL middleware so query logging survives the DBAL 3 → 4 transition. The 3.0.0 release does not change that positioning: it is still a migration bridge, not a strategic platform dependency. Value accrues only if query traffic traverses Doctrine DBAL; for an Eloquent/PDO-only Laravel stack it is inert.

Architecture fit. DBAL middleware is still the sanctioned extension point (Configuration::setMiddlewares()), so the package sits on a supported seam. The fit test remains binary: does any production read/write path use a Doctrine DBAL connection? Laravel’s Eloquent path does not; DB::listen() / QueryExecuted / Telescope already covers it. If DBAL appears only via schema operations or a package-owned connection, the package is a precise fit. If not, it is a solution without a problem.

Integration feasibility. Still low effort, but 3.0.0 raises the floor slightly. composer require firehed/dbal-logger now requires PHP 8.2+. The QueryLogger and DbalLogger interfaces are merged into a single DbalLogger, so any spike or wrapper code written against 2.x must be reworked. Native type declarations mean our redaction/adapter layer must implement the exact new signatures. Realistically 2–3 story points for a fresh spike, plus redaction and sampling. The code remains small and MIT-licensed, so it is auditable quickly.

Technical risk.

• Adoption risk, high. No change in the underlying community signal: very low stars, no dependents, single maintainer. The 3.0.0 release shows active maintenance and a broadened CI matrix (PHP 8.5 / 8.6-dev), which is a positive signal for engagement, but it does not constitute production validation at scale. Bus factor is still 1.
• Mitigation, strong. The package is small, MIT, and narrowly scoped. Forking or vendoring the middleware into our namespace remains a credible exit and should be the assumed fallback.
• API churn risk, elevated from moderate to moderate-high. 3.0.0 is a breaking release: PHP 8.1 dropped, interfaces merged, native types added, and stopQuery() now receives the exception. This confirms the package’s interface surface is still moving. We must pin both DBAL and this package, and cover the pairing in CI.
• Data-exposure risk, high and now broader. SQL loggers capture bound parameters. The new failure path is a second exposure surface: stopQuery() now receives the exception, and exception messages from DBAL can contain SQL fragments and parameter context. Redaction must cover both query parameters and exception payloads.
• Blast-radius risk, moderate. A logger that throws inside the middleware path can still fail the query it is observing. Defensive wrapping remains mandatory. The new error callback is useful for telemetry but must not introduce a new throw path.
• Silent no-op risk, improved but not eliminated. Failure tracking in stopQuery() gives us a way to assert that known queries and known failures are observed. That is a genuine operational improvement, but it does not prove the middleware is registered on the connection actually handling production traffic.

Key questions for the team.

1. Does any production read/write path use Doctrine DBAL, or is it exclusively Eloquent/PDO? (composer why doctrine/dbal answers this in minutes.)
2. Are we on PHP 8.2+ across all environments that would run this middleware? If not, 3.0.0 is blocked until the runtime upgrade lands.
3. Which DBAL major/minor are we pinned to, and is a DBAL 4 move on the roadmap? If DBAL 4 is imminent, the migration-bridge value is highest right now.
4. What does Laravel’s built-in query listener fail to give us that motivates this at all?
5. Do we have an adapter/redaction layer written against the 2.x QueryLogger interface? If so, who owns the merge to the unified DbalLogger and the new stopQuery() signature?
6. Will exception payloads from stopQuery() be redacted before they reach the log pipeline, or would this introduce a new PII surface?
7. Who owns the fork if upstream goes quiet for 12 months?

Integration Approach

Stack fit. Accept only under one of two conditions: (a) we are mid-migration to DBAL 4 and need parity with the removed SQLLogger, or (b) we have a non-Eloquent DBAL connection with no query observability. Otherwise decline and use DB::listen(). The 3.0.0 breaking changes do not change this decision rule; they only add upgrade preconditions. A “no-adopt, here’s why” decision remains a valid and likely TPM outcome.

Migration path. Sequence it as a compatibility shim, not a permanent layer:

1. Inventory DBAL usage and confirm PHP 8.2+ readiness on every target environment.
2. Spike against 3.0.0: register the middleware on a single non-production connection, confirm queries emit, and confirm stopQuery() receives failures.
3. Build a redaction layer in front of the logger — allowlist of loggable parameter types, hashing of string values, truncation on large blobs, and explicit redaction of exception messages. Treat this as required scope, not optional hardening.
4. Adopt, then track DBAL’s own logging story. Plan to remove the shim once we land on a first-party or internal replacement, and record that removal as a tracked follow-up.

Compatibility. Wrap the PSR-3 logger in a Laravel logging channel so retention, formatting, and shipping inherit our existing log pipeline. Verify the middleware coexists with any existing DBAL middleware — transaction wrappers and sharding/routing middleware can conflict on ordering, and middleware order determines what actually gets logged. Pin firehed/dbal-logger to ^3.0 and pair it with a tested DBAL version in CI. If any integration code targets the old QueryLogger interface, migrate it to DbalLogger and update stopQuery() to accept the exception argument.

Sequencing. Runtime/PHP compatibility check → spike → redaction (including exception redaction) → staging soak under realistic query volume → sampled rollout → full. Do not enable at 100% on first deploy. The new failure tracking is useful, but it also increases log volume on error paths; validate the backend impact before rollout.

Operational Impact

Maintenance. Ongoing code maintenance remains low, but 3.0.0 adds concrete upgrade work: PHP 8.2+ enforcement, interface consolidation, native types, and a changed stopQuery() signature. The governance cost is unchanged in kind but higher in near-term effort: pinning, version-pair testing in CI, and a named owner for the fork. Assign a backend platform owner even if they touch it twice a year.

Support. Community-only, no SLA, no vendor. Escalation path is “read the source,” which remains viable because of the package’s size. The 3.0.0 release and CI expansion are positive maintenance signals, but they do not constitute support. Set expectations accordingly: borrowed utility, not a supported component.

Scaling. Every logged query is synchronous I/O in the request path. At high QPS this becomes a measurable latency and log-volume contributor. The new failure telemetry can amplify this on incident paths, exactly when logging backends are already stressed. Mitigate with sampling, async/buffered handlers, strict level gating, and rate limiting for exception logging. Budget the log storage delta before enabling.

Failure modes to design against.

• Logger throws → query fails. Wrap in try/catch; logging must never break the transaction.
• Signature mismatch after 3.0.0 → adapter or redaction wrapper implements the old interface and fatals at runtime. Add contract tests against DbalLogger.
• Exception payload leakage → stopQuery() receives DBAL exceptions containing SQL or parameter context, which then land in a third-party aggregator. Redaction must cover exception messages, not just bound parameters.
• Silent no-op → middleware registered on a connection that is not actually used, giving false confidence. Assert in staging that known queries and known failures appear.
• Volume amplification → log backend saturation during an incident. Sample and rate-limit, especially failure logs.

Ramp-up. A mid-level engineer is productive in half a day for the middleware concept itself; 3.0.0 adds an hour or two for the unified interface and exception signature. The redaction design, now including exception payloads, is the genuinely hard part and deserves a security review pass. Total onboarding remains well under a sprint. If the fit questions come back negative, the right call is still to skip it and move on rather than spend the ramp-up budget.