在PHP项目中，尤其是那些依赖Doctrine DBAL进行数据库操作的应用，我们常常需要对SQL查询进行日志记录。这不仅是为了调试，更是为了性能分析、审计追踪和系统健康监控。想象一下，当你的应用出现数据库相关的性能瓶颈时，如果没有详细的查询日志，排查问题无异于大海捞针。
遇到的困境：DBAL SQLLogger 的“退役”
过去，Doctrine DBAL 提供了一个非常实用的 Doctrine\DBAL\Logging\SQLLogger 接口，它允许我们轻松地自定义SQL查询的记录方式。我们可以实现这个接口，将查询信息发送到文件、数据库，甚至是专门的监控服务。然而，随着Doctrine DBAL的演进，这个经典的 SQLLogger 被标记为弃用（deprecated），取而代之的是基于Middleware的日志记录方案。
起初，Middleware的引入看起来是个好主意，它更符合现代PHP框架的设计哲学。但很快，开发者们发现新的内置Middleware-based日志方案存在一些关键的局限性：
- 与PSR-3强绑定：它直接与PSR-3日志接口挂钩，这意味着你必须使用一个PSR-3兼容的Logger，并且其日志格式和级别往往是固定的，难以自定义。
- 日志格式和级别不可控：内置Middleware的日志输出格式和详细程度是预设的，如果你有特定的日志格式要求，或者希望根据不同的场景调整日志级别，就会感到束手无策。
- 缺少查询完成事件：最致命的一点是，新的方案没有提供查询完成（query completing）的事件钩子。这意味着你无法准确地记录每次查询的执行时间、成功与否，从而使得实现应用性能遥测（telemetry）和精细化性能监控变得几乎不可能。
这些限制让许多依赖旧版 SQLLogger 进行高级日志记录和性能分析的开发者陷入了困境。我们需要一个既能适应DBAL新架构，又能提供足够灵活性的解决方案。
firehed/dbal-logger：重拾DBAL日志的自由与掌控
正当大家为DBAL日志记录的未来感到迷茫时，firehed/dbal-logger 这个库应运而生，它提供了一个完美的解决方案，旨在重新实现并超越原版 SQLLogger 的功能，同时拥抱DBAL的Middleware新范式。
firehed/dbal-logger 的核心思想是提供一个与旧版 SQLLogger 类似但更强大的接口，并通过Middleware的方式无缝集成到DBAL中。它解决了上述所有痛点，让我们可以再次完全掌控SQL查询的日志记录。
核心优势与特性：
-
熟悉的API，现代的集成：它提供了
Firehed\DbalLogger\QueryLogger接口，其startQuery()和stopQuery()方法与旧版SQLLogger保持一致，大大降低了迁移成本。 -
高度可定制的日志格式：由于你可以实现自己的
QueryLogger，因此可以完全自定义日志的格式、内容和输出目标，不再受限于PSR-3或内置Middleware的限制。 -
完善的事件钩子：
stopQuery()方法的存在，意味着你可以准确捕捉到每次查询的完成事件，这对于记录查询耗时、分析慢查询、实现应用遥测（Telemetry）至关重要。 -
连接事件（可选）：除了查询事件，
Firehed\DbalLogger\DbalLogger接口还提供了connect()和disconnect()钩子，让你能更全面地监控数据库连接的生命周期。 -
多后端日志支持：内置的
ChainLogger允许你同时将日志发送到多个不同的后端，例如，一份日志用于文件存储，另一份用于实时监控系统。 - 明确的返回类型：接口添加了显式的返回类型，提升了代码的可读性和健壮性。
如何使用 firehed/dbal-logger 解决问题
使用 firehed/dbal-logger 非常简单，只需几步即可将它集成到你的Doctrine DBAL项目中。
第一步：安装
通过Composer安装库：
composer require firehed/dbal-logger
第二步：实现自定义Logger
创建一个类，实现 Firehed\DbalLogger\QueryLogger 接口。如果你还需要监控连接事件，可以实现 Firehed\DbalLogger\DbalLogger 接口。
logger = $logger;
}
public function startQuery(string $sql, array $params = [], array $types = []): void
{
$this->queries[] = [
'sql' => $sql,
'params' => $params,
'types' => $types,
'start' => microtime(true),
];
$this->logger->info('Executing SQL', ['sql' => $sql, 'params' => $params]);
}
public function stopQuery(): void
{
if (empty($this->queries)) {
return;
}
$lastQuery = array_pop($this->queries);
$duration = microtime(true) - $lastQuery['start'];
$this->logger->info('SQL executed successfully', [
'sql' => $lastQuery['sql'],
'duration_ms' => round($duration * 1000, 2),
]);
// 这里你可以将日志发送到任何你想要的地方，例如一个性能监控系统
// sendToTelemetryService($lastQuery['sql'], $duration);
}
}第三步：集成到DBAL配置
将你的自定义Logger包装在 Firehed\DbalLogger\Middleware 中，然后添加到DBAL的配置中。
pushHandler(new StreamHandler('php://stderr', Logger::DEBUG));
// 实例化你的自定义Logger
$myQueryLogger = new MyCustomSqlLogger($psrLogger);
// 将自定义Logger包装成Middleware
$middleware = new Middleware($myQueryLogger);
// 创建DBAL配置
$config = new Configuration();
// 将Middleware添加到配置中
$config->setMiddlewares([$middleware]);
// 数据库连接参数
$connectionParams = [
'url' => 'mysql://user:password@localhost/dbname',
];
// 创建数据库连接
$connection = DriverManager::getConnection($connectionParams, $config);
// 现在，所有通过 $connection 执行的SQL查询都将通过你的 MyCustomSqlLogger 进行记录
$connection->executeQuery('SELECT 1');
$connection->executeQuery('SELECT * FROM users WHERE id = ?', [1]);多后端日志记录
如果你需要将日志发送到多个不同的系统（例如，一个用于调试文件，一个用于性能监控），可以使用 ChainLogger：
setMiddlewares([$middleware]);
总结其优势与实际应用效果
firehed/dbal-logger 库的出现，为我们解决了Doctrine DBAL日志记录的诸多痛点，带来了显著的优势和实际应用效果：
- 高度灵活性与定制化：不再受限于固定的日志格式和输出目标。你可以根据项目的具体需求，定制SQL日志的每一个细节，无论是输出到文件、数据库、ELK堆栈，还是自定义的监控平台。
-
强大的性能监控能力：通过
stopQuery()事件，你可以精确地计算每次SQL查询的执行时间。这对于识别慢查询、优化数据库操作、实现应用性能监控（APM）和遥测至关重要。你可以轻松构建自己的慢查询报告或集成到第三方监控工具。 -
无缝的迁移路径：对于那些从旧版
SQLLogger迁移的项目，firehed/dbal-logger提供了几乎相同的API，使得迁移过程平滑而高效。 - 符合现代DBAL架构：它完美地融入了DBAL的Middleware体系，确保了与最新DBAL版本的兼容性和未来的可维护性。
- 提升开发效率与可观测性：清晰、可控的SQL日志能够大大简化调试过程，帮助开发者快速定位问题。同时，通过日志数据，团队可以更好地理解应用的数据库行为，提升整体系统的可观测性。
总之，firehed/dbal-logger 是一个不可多得的工具，它不仅弥补了Doctrine DBAL在日志记录方面的功能缺失，更赋予了开发者在数据库层面的强大掌控力。如果你正在寻找一个灵活、强大且易于集成的DBAL日志解决方案，那么 firehed/dbal-logger 绝对值得你尝试。它将帮助你的PHP应用在数据处理层面变得更加透明、高效和健壮。
