File Sql Logger Bundle Laravel Package

Getting Started

• Install the package with Composer and publish any provided config if the service provider exposes one.
• Start by reading the package README/config for how the Doctrine SQLLogger is registered. The key integration point is attaching the logger to the Doctrine DBAL connection used by Laravel, not just enabling a Laravel query listener.
• Enable it first in local or staging, perform a known write operation (create, update, delete, raw INSERT/UPDATE/DELETE), then inspect the configured log channel.
• Best first use case: verify exactly which mutable queries a request, job, or artisan command executes. This is especially useful for auditing unexpected writes, debugging mass updates, and confirming transaction behavior.
• Confirm early whether the logger captures only mutating statements or all statements. Treat it as a mutable-query logger unless the package documentation says otherwise.

Implementation Patterns

• Local write debugging: enable the logger via environment-specific config, reproduce the write path, then disable it. Keep it off by default in production unless you have a clear audit requirement and log-retention plan.
• Request/job auditing: wrap critical imports, sync jobs, and admin actions with a known start/end boundary, then review the mutable queries emitted during that window.
• Feature-test assertions: in integration tests, enable the logger around an action and assert that only expected INSERT, UPDATE, or DELETE statements occur. This catches accidental writes from observers, events, or cascading model saves.
• Custom log channel: route output to a dedicated daily/single file or stderr in containerized environments. This keeps write-audit logs separate from normal Laravel logs.
• Multi-connection setup: register the logger on each Doctrine connection you care about. If using read/write splitting, attach it to the write connection; otherwise expected mutations may not appear.
• Pair with Laravel tooling: use Laravel’s query listener or Telescope for general read-query profiling, and use this package for Doctrine-level mutable-query visibility. They answer different questions.
• Staging verification: run the logger for a bounded period in staging to compare expected write patterns against actual SQL before promoting changes.

Gotchas and Tips

• Layer mismatch: this is a Doctrine DBAL SQLLogger. Queries executed entirely outside the Doctrine connection, or through a different PDO handle, may not be captured.
• Mutable-only visibility: if the logger filters to mutating queries, missing SELECTs are expected. Do not use it as a complete query profiler.
• Bindings and sensitive data: log entries may include SQL placeholders and bound parameters. Review redaction before enabling in shared environments; avoid logging secrets, tokens, or PII.
• Log volume and overhead: write-heavy jobs can generate large logs and add measurable overhead. Scope logging to specific environments, channels, or short debugging windows.
• Transaction timing: startQuery/stopQuery timings can be misleading inside long transactions. Use the SQL text and sequence as the primary signal, not elapsed time alone.
• Config cache: after changing logger config or channels, run php artisan config:clear in local/staging. Cached config is a common reason “nothing logs.”
• Connection wiring: if no entries appear, verify the logger is actually set on the Doctrine connection, the connection is the one executing the write, and the log channel is writable.
• Version pinning: v1.0.0 is an initial release. Pin the version and verify compatibility with your Laravel and Doctrine DBAL versions before broad rollout.
• Extension points: use a custom Laravel log channel or formatter if available; otherwise keep the package’s logger as the capture layer and post-process logs rather than modifying vendor code.