Introduce logging middleware

[morozov]

Q	A
Type	improvement
BC Break	no

Closes #4941.

This middleware is meant to replace the SQLLogger interface but it's not a drop-in replacement:

1. It will log the statements and their parameters in the form in which they are passed to the DBAL driver (i.e. with list parameters expanded and named parameters converted to the positional ones).
2. There is no equivalent of the stopQuery() method. If instrumentation around the query methods is needed, it should be implemented as a separate middleware.

Technical details:

1. "Connecting" is logged in the driver but "Disconnecting" is logged in the connection. This is a bit asymmetric but there's a reason: the connection parameters in the DBAL format are only available at the driver level but the driver doesn't handle disconnection.
2. The middleware doesn't log exceptions. The severity of the exception as well as the need to log it should be determined by the component that handles the exception.

Test changes:

1. The IBM DB2 connection test is removed as it assumes that Connection::getWrappedConnection() will return a driver connection while it may return a middleware (see Deprecate Connection::getWrappedConnection(), mark Connection::connect() internal #4966). The error handling during prepare() cannot always be tested in isolation and is covered in a more reliable way in

   dbal/tests/Functional/ConnectionTest.php

   Line 413 in 07453f2

   public function testExceptionOnPrepareAndExecute(): void

2. The assertion in testDeterminesDatabasePlatformWhenConnectingToNonExistentDatabase() is removed since the middleware driver always implements the VersionAwarePlatformDriver, even if the wrapped driver doesn't, so based on that, the wrapper connection will always connect to detect the server version. This will be likely addressed by Remove VersionAwarePlatformDriver and ServerInfoAwareConnection #4764 in 4.0.0. UPD: this entire feature is pointless (Remove VersionAwarePlatformDriver and ServerInfoAwareConnection #4764 (comment)).

TODO:

• Add tests for the logger middleware.
• Remove the dependency of ResultCacheTest on DebugStack (Refactor query caching tests #5008).
• Remove the "Temporarily enable Monolog in the test suite" commit.

[greg0ire]

One might think we are giving an indication about the number of characters. How about this instead:

Suggested change

	$params['password'] = '******';
	$params['password'] = '<redacted>';

[morozov]

I discussed this with my colleague and we came to the same conclusion. Let's change it.

[derrabus]

Follow-up: doctrine/DoctrineBundle#1429

[Igor100]

Hello @morozov
How to use this midleware instead the construction:
$doctrine = $this->getDoctrine();
$doctrineConnection = $doctrine->getConnection();
$stack = new \Doctrine\DBAL\Logging\DebugStack();
$doctrineConnection->getConfiguration()->setSQLLogger($stack);
...... src sql using .......
dd($stack)

[morozov]

@Igor100 here's an example:

dbal/tests/TestUtil.php

Lines 66 to 71 in 69a38c2

	$logger = new Logger('PHPUnit');
	$logger->pushHandler(new StreamHandler('/tmp/dbal.log', Logger::DEBUG));
	$logger->pushProcessor(new PsrLogMessageProcessor(null, true));
	$configuration = (new Configuration())->setMiddlewares([new Logging\Middleware($logger)]);
	$conn = DriverManager::getConnection(self::getConnectionParams(), $configuration);

[Tobion]

Hello. What's the recommended way of disabling sql logging for certain parts of the app?
Removing the sql logger from the connection configuration as done in doctrine/DoctrineBundle#787
does not seem to work anymore. The middleware will always log.
See also symfony/symfony#45974

[morozov]

If you're using Monolog, you can try doing popHandler() / pushHandler() in those parts that need logging to be disabled. Otherwise, it depends on the logger.

[mkopinsky]

If SQLLogger is deprecated in 3.2, does that mean that it's safe to continue using in ^3.0?

[derrabus]

If SQLLogger is deprecated in 3.2, does that mean that it's safe to continue using in ^3.0?

Yes. It means your code will break when upgrading to 4.0.

[raziel057]

From user perspective, deprecating the SQLLogger seems a bit weird to me as we are not able anymore to change it after the connection is created according to different contexts. Maybe you could provide a way to change or remove the logger in the connection decorator created by the middleware?

[morozov]

The middleware is just an adapter between the DBAL driver and a PSR-3 logger. If the logger needs to implement any application-specific logic, it should be implemented in the logger. See #4967 (comment) for example.

[nayodahl]

Hello @morozov ,
How do you use the equivalent of the deprecated DebugStack(), if there is any ?
I'm ok with adding the Logging\Middleware to the connection's configuration like this :

$logger = new Logger('PHPUnit');
$logger->pushHandler(new StreamHandler('/tmp/dbal.log', Logger::DEBUG));
$logger->pushProcessor(new PsrLogMessageProcessor(null, true));

$configuration = (new Configuration())->setMiddlewares([new Logging\Middleware($logger)]);
$conn          = DriverManager::getConnection(self::getConnectionParams(), $configuration);

But then, how do you get the debugStack like the profiler does for exemple ?
I used to simply inject it in an eventListener and do stuff of the queries...

[morozov]

@nayodahl there's no equivalent of DebugStack. You can implement your own middleware that will wrap calls to the methods you're interested in in the code that captures the time their execution takes. Then you'll need to register both these middlewares. Probably the profiling one first (since you don't want to profile logging) and then the logging one.