README

A customizable query logger for Doctrine DBAL.

This can be used in a number of ways:

Debug logging
Telemetry
Capturing SQL queries for audit trails
And more! Be creative!

Installation

composer require firehed/dbal-logger

Usage

Implement Firehed\DbalLogger\DbalLogger
Wrap it in the middleware
Add the middleware to your DBAL configuration

use Firehed\DbalLogger\DbalLogger;
use Firehed\DbalLogger\Middleware;

class MyLogger implements DbalLogger
{
    public function startQuery(string $sql, ?array $params = null, ?array $types = null): void
    {
        // Called before each query
        // Commonly: store $sql and start a timer
    }

    public function stopQuery(?Throwable $exception): void
    {
        // Called after each query completes (or fails)
        // Commonly: determine the query duration based on the start timer and log or send a telemetry event
    }

    public function connect(): void
    {
        // Called when a connection is established
    }

    public function disconnect(): void
    {
        // Called when a connection is closed
    }
}

$logger = new MyLogger();
$middleware = new Middleware($logger);

// Add to your Doctrine\DBAL\Configuration
$config = new \Doctrine\DBAL\Configuration();
$config->setMiddlewares([$middleware]);

$connection = \Doctrine\DBAL\DriverManager::getConnection($connectionDetails, $config);

Tip

Use dependency injection to provide services to your DbalLogger implementation, such as a log writer (e.g. PSR-3) or telemetry system.

Error Handling

The stopQuery() method receives the exception if a query fails, or null on success. This enables query timing, failure tracking, and telemetry:

public function stopQuery(?Throwable $exception): void
{
    $duration = hrtime(true) - $this->start;
    if ($exception !== null) {
        $this->logger->error('Query failed', [
            'sql' => $this->sql,
            'duration' => $duration,
            'exception' => $exception,
        ]);
    } else {
        $this->logger->debug('Query completed', [
            'sql' => $this->sql,
            'duration' => $duration,
        ]);
    }
}

Multiple Loggers

Use ChainLogger to send events to multiple loggers:

use Firehed\DbalLogger\ChainLogger;
use Firehed\DbalLogger\Middleware;

$chain = new ChainLogger([
    new QueryLogger(),
    new MetricsLogger(),
    new AuditTrailLogger(),
]);

$config = new \Doctrine\DBAL\Configuration();
$config->setMiddlewares([new Middleware($chain)]);

Migrating from SQLLogger

If you're migrating from the deprecated Doctrine\DBAL\Logging\SQLLogger:

Change implements SQLLogger to implements DbalLogger
Add connect(): void and disconnect(): void methods (can be no-ops)
The stopQuery() method now accepts ?Throwable $exception
Wrap your logger in the middleware and configure DBAL:

-$config->setSQLLogger($yourSQLLogger);
+$config->setMiddlewares([new Middleware($yourLogger)]);

Why this library?

Doctrine's bundled middleware-based replacement for SQLLogger has limitations:

It's tied directly to a PSR-3 logger
The log format and levels cannot be customized
There is no event for queries completing, making telemetry impossible

This library provides full control over logging behavior while using DBAL's middleware system.

Misc

This project follows semantic versioning.

Please use Github for reporting any issues or making any feature requests.

firehed / dbal-logger

Maintainers

Package info

Statistics

Security