[HttpKernel][MonologBridge][FrameworkBundle] Revisit wiring of debug loggers

nicolas-grekas · nicolas-grekas · commit 187b42a8aec8 · 2023-08-05T14:37:05.000+02:00
diff --git a/src/Symfony/Bridge/Monolog/CHANGELOG.md b/src/Symfony/Bridge/Monolog/CHANGELOG.md
@@ -5,6 +5,7 @@ CHANGELOG
 ---
 
  * Add native return type to `Logger::clear()` and to `DebugProcessor::clear()`
+ * Deprecate class `Logger`, use HttpKernel's `DebugLoggerConfigurator` instead
 
 6.1
 ---
diff --git a/src/Symfony/Bridge/Monolog/Logger.php b/src/Symfony/Bridge/Monolog/Logger.php
@@ -11,14 +11,16 @@
 
 namespace Symfony\Bridge\Monolog;
 
+trigger_deprecation('symfony/monolog-bridge', '5.4', 'The "%s" class is deprecated, use HttpKernel\'s DebugLoggerConfigurator instead.', Logger::class);
+
 use Monolog\Logger as BaseLogger;
 use Monolog\ResettableInterface;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpKernel\Log\DebugLoggerInterface;
 use Symfony\Contracts\Service\ResetInterface;
 
 /**
- * @author Fabien Potencier <fabien@symfony.com>
+ * @deprecated since Symfony 6.4, use HttpKernel's DebugLoggerConfigurator instead
  */
 class Logger extends BaseLogger implements DebugLoggerInterface, ResetInterface
 {
diff --git a/src/Symfony/Bridge/Monolog/Tests/LoggerTest.php b/src/Symfony/Bridge/Monolog/Tests/LoggerTest.php
@@ -18,6 +18,9 @@
 use Symfony\Bridge\Monolog\Processor\DebugProcessor;
 use Symfony\Component\HttpFoundation\Request;
 
+/**
+ * @group legacy
+ */
 class LoggerTest extends TestCase
 {
     public function testGetLogsWithoutDebugProcessor()
diff --git a/src/Symfony/Bundle/FrameworkBundle/CHANGELOG.md b/src/Symfony/Bundle/FrameworkBundle/CHANGELOG.md
@@ -10,6 +10,8 @@ CHANGELOG
  * Add `DomCrawlerAssertionsTrait::assertAnySelectorTextContains(string $selector, string $text)`
  * Add `DomCrawlerAssertionsTrait::assertAnySelectorTextSame(string $selector, string $text)`
  * Add `DomCrawlerAssertionsTrait::assertAnySelectorTextNotContains(string $selector, string $text)`
+ * Deprecate `EnableLoggerDebugModePass`, use argument `$debug` of HttpKernel's `Logger` instead
+ * Deprecate `AddDebugLogProcessorPass::configureLogger()`, use HttpKernel's `DebugLoggerConfigurator` instead
 
 6.3
 ---
diff --git a/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Compiler/AddDebugLogProcessorPass.php b/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Compiler/AddDebugLogProcessorPass.php
@@ -32,16 +32,19 @@ public function process(ContainerBuilder $container)
             return;
         }
 
-        $definition = $container->getDefinition('monolog.logger_prototype');
-        $definition->setConfigurator([__CLASS__, 'configureLogger']);
-        $definition->addMethodCall('pushProcessor', [new Reference('debug.log_processor')]);
+        $container->getDefinition('monolog.logger_prototype')
+            ->setConfigurator([new Reference('debug.debug_logger_configurator'), 'pushDebugLogger']);
     }
 
     /**
+     * @deprecated since Symfony 6.4, use HttpKernel's DebugLoggerConfigurator instead
+     *
      * @return void
      */
     public static function configureLogger(mixed $logger)
     {
+        trigger_deprecation('symfony/framework-bundle', '6.4', 'The "%s()" method is deprecated, use HttpKernel\'s DebugLoggerConfigurator instead.', __METHOD__);
+
         if (\is_object($logger) && method_exists($logger, 'removeDebugLogger') && \in_array(\PHP_SAPI, ['cli', 'phpdbg'], true)) {
             $logger->removeDebugLogger();
         }
diff --git a/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Compiler/EnableLoggerDebugModePass.php b/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Compiler/EnableLoggerDebugModePass.php
@@ -11,10 +11,15 @@
 
 namespace Symfony\Bundle\FrameworkBundle\DependencyInjection\Compiler;
 
+trigger_deprecation('symfony/framework-bundle', '6.4', 'The "%s" class is deprecated, use argument $debug of HttpKernel\'s Logger instead.', EnableLoggerDebugModePass::class);
+
 use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\HttpKernel\Log\Logger;
 
+/**
+ * @deprecated since Symfony 6.4, use argument $debug of HttpKernel's Logger instead
+ */
 final class EnableLoggerDebugModePass implements CompilerPassInterface
 {
     public function process(ContainerBuilder $container): void
@@ -32,7 +37,7 @@ public function process(ContainerBuilder $container): void
 
     public static function configureLogger(Logger $logger): void
     {
-        if (!\in_array(\PHP_SAPI, ['cli', 'phpdbg'], true) && method_exists($logger, 'enableDebug')) {
+        if (!\in_array(\PHP_SAPI, ['cli', 'phpdbg'], true)) {
             $logger->enableDebug();
         }
     }
diff --git a/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php b/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php
@@ -101,6 +101,7 @@
 use Symfony\Component\HttpKernel\Controller\ValueResolverInterface;
 use Symfony\Component\HttpKernel\DataCollector\DataCollectorInterface;
 use Symfony\Component\HttpKernel\DependencyInjection\Extension;
+use Symfony\Component\HttpKernel\Log\DebugLoggerConfigurator;
 use Symfony\Component\Lock\LockFactory;
 use Symfony\Component\Lock\LockInterface;
 use Symfony\Component\Lock\PersistingStoreInterface;
@@ -1171,7 +1172,11 @@ private function registerDebugConfiguration(array $config, ContainerBuilder $con
             $definition = new Definition(DebugProcessor::class);
             $definition->setPublic(false);
             $definition->addArgument(new Reference('request_stack'));
+            $definition->addTag('kernel.reset', ['method' => 'reset']);
             $container->setDefinition('debug.log_processor', $definition);
+
+            $container->register('debug.debug_logger_configurator', DebugLoggerConfigurator::class)
+                ->setArguments([new Reference('debug.log_processor')]);
         }
     }
 
diff --git a/src/Symfony/Bundle/FrameworkBundle/FrameworkBundle.php b/src/Symfony/Bundle/FrameworkBundle/FrameworkBundle.php
@@ -183,7 +183,6 @@ public function build(ContainerBuilder $container)
         $container->addCompilerPass(new RemoveUnusedSessionMarshallingHandlerPass());
 
         if ($container->getParameter('kernel.debug')) {
-            $container->addCompilerPass(new EnableLoggerDebugModePass(), PassConfig::TYPE_BEFORE_OPTIMIZATION, -33);
             $container->addCompilerPass(new AddDebugLogProcessorPass(), PassConfig::TYPE_BEFORE_OPTIMIZATION, 2);
             $container->addCompilerPass(new UnusedTagsPass(), PassConfig::TYPE_AFTER_REMOVING);
             $container->addCompilerPass(new ContainerBuilderDebugDumpPass(), PassConfig::TYPE_BEFORE_REMOVING, -255);
diff --git a/src/Symfony/Component/ErrorHandler/ErrorRenderer/HtmlErrorRenderer.php b/src/Symfony/Component/ErrorHandler/ErrorRenderer/HtmlErrorRenderer.php
@@ -16,7 +16,7 @@
 use Symfony\Component\HttpFoundation\RequestStack;
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\HttpKernel\Debug\FileLinkFormatter;
-use Symfony\Component\HttpKernel\Log\DebugLoggerInterface;
+use Symfony\Component\HttpKernel\Log\DebugLoggerConfigurator;
 use Symfony\Component\VarDumper\Cloner\Data;
 use Symfony\Component\VarDumper\Dumper\HtmlDumper;
 
@@ -144,7 +144,7 @@ private function renderException(FlattenException $exception, string $debugTempl
             'exceptionMessage' => $exceptionMessage,
             'statusText' => $statusText,
             'statusCode' => $statusCode,
-            'logger' => $this->logger instanceof DebugLoggerInterface ? $this->logger : null,
+            'logger' => DebugLoggerConfigurator::getDebugLogger($this->logger),
             'currentContent' => \is_string($this->outputBuffer) ? $this->outputBuffer : ($this->outputBuffer)(),
         ]);
     }
diff --git a/src/Symfony/Component/ErrorHandler/composer.json b/src/Symfony/Component/ErrorHandler/composer.json
@@ -21,12 +21,13 @@
         "symfony/var-dumper": "^5.4|^6.0|^7.0"
     },
     "require-dev": {
-        "symfony/http-kernel": "^5.4|^6.0|^7.0",
+        "symfony/http-kernel": "^6.4|^7.0",
         "symfony/serializer": "^5.4|^6.0|^7.0",
         "symfony/deprecation-contracts": "^2.5|^3"
     },
     "conflict": {
-        "symfony/deprecation-contracts": "<2.5"
+        "symfony/deprecation-contracts": "<2.5",
+        "symfony/http-kernel": "<6.4"
     },
     "autoload": {
         "psr-4": { "Symfony\\Component\\ErrorHandler\\": "" },
diff --git a/src/Symfony/Component/HttpKernel/CHANGELOG.md b/src/Symfony/Component/HttpKernel/CHANGELOG.md
@@ -9,6 +9,8 @@ CHANGELOG
  * Add optional `$className` parameter to `ControllerEvent::getAttributes()`
  * Add native return types to `TraceableEventDispatcher` and to `MergeExtensionConfigurationPass`
  * Add argument `$validationFailedStatusCode` to `#[MapQueryString]` and `#[MapRequestPayload]`
+ * Add argument `$debug` to `Logger`
+ * Add class `DebugLoggerConfigurator`
 
 6.3
 ---
diff --git a/src/Symfony/Component/HttpKernel/DataCollector/LoggerDataCollector.php b/src/Symfony/Component/HttpKernel/DataCollector/LoggerDataCollector.php
@@ -15,6 +15,7 @@
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\RequestStack;
 use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\HttpKernel\Log\DebugLoggerConfigurator;
 use Symfony\Component\HttpKernel\Log\DebugLoggerInterface;
 use Symfony\Component\VarDumper\Cloner\Data;
 
@@ -25,18 +26,15 @@
  */
 class LoggerDataCollector extends DataCollector implements LateDataCollectorInterface
 {
-    private DebugLoggerInterface $logger;
+    private ?DebugLoggerInterface $logger;
     private ?string $containerPathPrefix;
     private ?Request $currentRequest = null;
     private ?RequestStack $requestStack;
     private ?array $processedLogs = null;
 
     public function __construct(object $logger = null, string $containerPathPrefix = null, RequestStack $requestStack = null)
     {
-        if ($logger instanceof DebugLoggerInterface) {
-            $this->logger = $logger;
-        }
-
+        $this->logger = DebugLoggerConfigurator::getDebugLogger($logger);
         $this->containerPathPrefix = $containerPathPrefix;
         $this->requestStack = $requestStack;
     }
@@ -46,17 +44,9 @@ public function collect(Request $request, Response $response, \Throwable $except
         $this->currentRequest = $this->requestStack && $this->requestStack->getMainRequest() !== $request ? $request : null;
     }
 
-    public function reset(): void
-    {
-        if (isset($this->logger)) {
-            $this->logger->clear();
-        }
-        parent::reset();
-    }
-
     public function lateCollect(): void
     {
-        if (isset($this->logger)) {
+        if ($this->logger) {
             $containerDeprecationLogs = $this->getContainerDeprecationLogs();
             $this->data = $this->computeErrorsCount($containerDeprecationLogs);
             // get compiler logs later (only when they are needed) to improve performance
diff --git a/src/Symfony/Component/HttpKernel/DependencyInjection/LoggerPass.php b/src/Symfony/Component/HttpKernel/DependencyInjection/LoggerPass.php
@@ -14,6 +14,7 @@
 use Psr\Log\LoggerInterface;
 use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Definition;
 use Symfony\Component\DependencyInjection\Reference;
 use Symfony\Component\HttpFoundation\RequestStack;
 use Symfony\Component\HttpKernel\Log\Logger;
@@ -37,8 +38,21 @@ public function process(ContainerBuilder $container)
             return;
         }
 
+        if ($debug = $container->getParameter('kernel.debug')) {
+            // Build an expression that will be equivalent to `!in_array(PHP_SAPI, ['cli', 'phpdbg'])`
+            $debug = (new Definition('bool'))
+                ->setFactory('in_array')
+                ->setArguments([
+                    (new Definition('string'))->setFactory('constant')->setArguments(['PHP_SAPI']),
+                    ['cli', 'phpdbg']
+                ]);
+            $debug = (new Definition('bool'))
+                ->setFactory('in_array')
+                ->setArguments([$debug, [false]]);
+        }
+
         $container->register('logger', Logger::class)
-            ->setArguments([null, null, null, new Reference(RequestStack::class)])
+            ->setArguments([null, null, null, new Reference(RequestStack::class), $debug])
             ->setPublic(false);
     }
 }
diff --git a/src/Symfony/Component/HttpKernel/EventListener/ErrorListener.php b/src/Symfony/Component/HttpKernel/EventListener/ErrorListener.php
@@ -26,7 +26,7 @@
 use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
 use Symfony\Component\HttpKernel\HttpKernelInterface;
 use Symfony\Component\HttpKernel\KernelEvents;
-use Symfony\Component\HttpKernel\Log\DebugLoggerInterface;
+use Symfony\Component\HttpKernel\Log\DebugLoggerConfigurator;
 
 /**
  * @author Fabien Potencier <fabien@symfony.com>
@@ -231,7 +231,7 @@ protected function duplicateRequest(\Throwable $exception, Request $request): Re
         $attributes = [
             '_controller' => $this->controller,
             'exception' => $exception,
-            'logger' => $this->logger instanceof DebugLoggerInterface ? $this->logger : null,
+            'logger' => DebugLoggerConfigurator::getDebugLogger($this->logger),
         ];
         $request = $request->duplicate(null, null, $attributes);
         $request->setMethod('GET');
diff --git a/src/Symfony/Component/HttpKernel/Log/DebugLoggerConfigurator.php b/src/Symfony/Component/HttpKernel/Log/DebugLoggerConfigurator.php
@@ -0,0 +1,56 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpKernel\Log;
+
+use Monolog\Logger;
+use Symfony\Component\HttpKernel\Log\DebugLoggerInterface;
+
+/**
+ * @author Nicolas Grekas <p@tchwork.com>
+ */
+class DebugLoggerConfigurator
+{
+    private ?DebugLoggerInterface $processor = null;
+
+    public function __construct(DebugLoggerInterface $processor, bool $enable = null)
+    {
+        if ($enable ?? \in_array(\PHP_SAPI, ['cli', 'phpdbg'], true)) {
+            $this->processor = $processor;
+        }
+    }
+
+    public function pushDebugLogger(Logger $logger): void
+    {
+        if ($this->processor) {
+            $logger->pushProcessor($this->processor);
+        }
+    }
+
+    public static function getDebugLogger(mixed $logger): ?DebugLoggerInterface
+    {
+        if ($logger instanceof DebugLoggerInterface) {
+            return $logger;
+        }
+
+        if (!$logger instanceof Logger) {
+            return null;
+        }
+
+        foreach ($logger->getProcessors() as $processor) {
+            if ($processor instanceof DebugLoggerInterface) {
+                return $processor;
+            }
+        }
+
+        return null;
+    }
+}
diff --git a/src/Symfony/Component/HttpKernel/Log/Logger.php b/src/Symfony/Component/HttpKernel/Log/Logger.php
@@ -57,7 +57,7 @@ class Logger extends AbstractLogger implements DebugLoggerInterface
     /**
      * @param string|resource|null $output
      */
-    public function __construct(string $minLevel = null, $output = null, callable $formatter = null, private readonly ?RequestStack $requestStack = null)
+    public function __construct(string $minLevel = null, $output = null, callable $formatter = null, private readonly ?RequestStack $requestStack = null, bool $debug = false)
     {
         if (null === $minLevel) {
             $minLevel = null === $output || 'php://stdout' === $output || 'php://stderr' === $output ? LogLevel::ERROR : LogLevel::WARNING;
@@ -82,6 +82,7 @@ public function __construct(string $minLevel = null, $output = null, callable $f
         if ($output && false === $this->handle = \is_resource($output) ? $output : @fopen($output, 'a')) {
             throw new InvalidArgumentException(sprintf('Unable to open "%s".', $output));
         }
+        $this->debug = $debug;
     }
 
     public function enableDebug(): void
diff --git a/src/Symfony/Component/HttpKernel/Tests/DataCollector/LoggerDataCollectorTest.php b/src/Symfony/Component/HttpKernel/Tests/DataCollector/LoggerDataCollectorTest.php
@@ -167,18 +167,6 @@ public function testCollect($nb, $logs, $expectedLogs, $expectedDeprecationCount
         }
     }
 
-    public function testReset()
-    {
-        $logger = $this
-            ->getMockBuilder(DebugLoggerInterface::class)
-            ->onlyMethods(['countErrors', 'getLogs', 'clear'])
-            ->getMock();
-        $logger->expects($this->once())->method('clear');
-
-        $c = new LoggerDataCollector($logger);
-        $c->reset();
-    }
-
     public static function getCollectTestData()
     {
         yield 'simple log' => [

Original file line number	Diff line number	Diff line change
`@@ -18,6 +18,9 @@`
`18`	`18`	`use Symfony\Bridge\Monolog\Processor\DebugProcessor;`
`19`	`19`	`use Symfony\Component\HttpFoundation\Request;`
`20`	`20`
	`21`	`+/**`
	`22`	`+ * @group legacy`
	`23`	`+ */`
`21`	`24`	`class LoggerTest extends TestCase`
`22`	`25`	`{`
`23`	`26`	`public function testGetLogsWithoutDebugProcessor()`
Original file line number	Diff line number	Diff line change
`@@ -32,16 +32,19 @@ public function process(ContainerBuilder $container)`
`32`	`32`	`return;`
`33`	`33`	`}`
`34`	`34`
`35`		`- $definition = $container->getDefinition('monolog.logger_prototype');`
`36`		`- $definition->setConfigurator([__CLASS__, 'configureLogger']);`
`37`		`- $definition->addMethodCall('pushProcessor', [new Reference('debug.log_processor')]);`
	`35`	`+ $container->getDefinition('monolog.logger_prototype')`
	`36`	`+ ->setConfigurator([new Reference('debug.debug_logger_configurator'), 'pushDebugLogger']);`
`38`	`37`	`}`
`39`	`38`
`40`	`39`	`/**`
	`40`	`+ * @deprecated since Symfony 6.4, use HttpKernel's DebugLoggerConfigurator instead`
	`41`	`+ *`
`41`	`42`	`* @return void`
`42`	`43`	`*/`
`43`	`44`	`public static function configureLogger(mixed $logger)`
`44`	`45`	`{`
	`46`	`+ trigger_deprecation('symfony/framework-bundle', '6.4', 'The "%s()" method is deprecated, use HttpKernel\'s DebugLoggerConfigurator instead.', __METHOD__);`
	`47`	`+`
`45`	`48`	`if (\is_object($logger) && method_exists($logger, 'removeDebugLogger') && \in_array(\PHP_SAPI, ['cli', 'phpdbg'], true)) {`
`46`	`49`	`$logger->removeDebugLogger();`
`47`	`50`	`}`
Original file line number	Diff line number	Diff line change
`@@ -11,10 +11,15 @@`
`11`	`11`
`12`	`12`	`namespace Symfony\Bundle\FrameworkBundle\DependencyInjection\Compiler;`
`13`	`13`
	`14`	`+trigger_deprecation('symfony/framework-bundle', '6.4', 'The "%s" class is deprecated, use argument $debug of HttpKernel\'s Logger instead.', EnableLoggerDebugModePass::class);`
	`15`	`+`
`14`	`16`	`use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;`
`15`	`17`	`use Symfony\Component\DependencyInjection\ContainerBuilder;`
`16`	`18`	`use Symfony\Component\HttpKernel\Log\Logger;`
`17`	`19`
	`20`	`+/**`
	`21`	`+ * @deprecated since Symfony 6.4, use argument $debug of HttpKernel's Logger instead`
	`22`	`+ */`
`18`	`23`	`final class EnableLoggerDebugModePass implements CompilerPassInterface`
`19`	`24`	`{`
`20`	`25`	`public function process(ContainerBuilder $container): void`
`@@ -32,7 +37,7 @@ public function process(ContainerBuilder $container): void`
`32`	`37`
`33`	`38`	`public static function configureLogger(Logger $logger): void`
`34`	`39`	`{`
`35`		`- if (!\in_array(\PHP_SAPI, ['cli', 'phpdbg'], true) && method_exists($logger, 'enableDebug')) {`
	`40`	`+ if (!\in_array(\PHP_SAPI, ['cli', 'phpdbg'], true)) {`
`36`	`41`	`$logger->enableDebug();`
`37`	`42`	`}`
`38`	`43`	`}`