feature #35978 [Messenger] Show message & handler(s) class description in debug:messenger (ogizanagi)

This PR was merged into the 5.1-dev branch.

Discussion
----------

[Messenger] Show message & handler(s) class description in debug:messenger

| Q             | A
| ------------- | ---
| Branch?       | master<!-- see below -->
| Bug fix?      | no
| New feature?  | yes <!-- please update src/**/CHANGELOG.md files -->
| Deprecations? | no <!-- please update UPGRADE-*.md and src/**/CHANGELOG.md files -->
| Tickets       | N/A <!-- prefix each issue number with "Fix #", if any -->
| License       | MIT
| Doc PR        | N/A

Similar to the `debug:autowiring` command, add the messages & handlers class description to the `debug:messenger` command.

Messenger is a central piece in CQRS applications. Exposing the messages & handlers descriptions in this command is a great way to have a global vision of the covered use-cases (especially if there is a newcomer to the project).

Commits
-------

079efdff08 [Messenger] Show message & handler(s) class description in debug:messenger

src/Symfony/Component/Messenger/Command/DebugCommand.php

@@ -80,12 +80,20 @@ EOF
 
             $tableRows = [];
             foreach ($handlersByMessage as $message => $handlers) {
+                if ($description = self::getClassDescription($message)) {
+                    $tableRows[] = [sprintf('<comment>%s</>', $description)];
+                }
+
                 $tableRows[] = [sprintf('<fg=cyan>%s</fg=cyan>', $message)];
                 foreach ($handlers as $handler) {
                     $tableRows[] = [
                         sprintf('    handled by <info>%s</>', $handler[0]).$this->formatConditions($handler[1]),
                     ];
+                    if ($handlerDescription = self::getClassDescription($handler[0])) {
+                        $tableRows[] = [sprintf('               <comment>%s</>', $handlerDescription)];
+                    }
                 }
+                $tableRows[] = [''];
             }
 
             if ($tableRows) {
@@ -113,4 +121,20 @@ EOF
 
         return ' (when '.implode(', ', $optionsMapping).')';
     }
+
+    private static function getClassDescription(string $class): string
+    {
+        try {
+            $r = new \ReflectionClass($class);
+
+            if ($docComment = $r->getDocComment()) {
+                $docComment = preg_split('#\n\s*\*\s*[\n@]#', substr($docComment, 3, -2), 2)[0];
+
+                return trim(preg_replace('#\s*\n\s*\*\s*#', ' ', $docComment));
+            }
+        } catch (\ReflectionException $e) {
+        }
+
+        return '';
+    }
 }

src/Symfony/Component/Messenger/Tests/Command/DebugCommandTest.php

@@ -16,6 +16,8 @@ use Symfony\Component\Console\Tester\CommandTester;
 use Symfony\Component\Messenger\Command\DebugCommand;
 use Symfony\Component\Messenger\Tests\Fixtures\DummyCommand;
 use Symfony\Component\Messenger\Tests\Fixtures\DummyCommandHandler;
+use Symfony\Component\Messenger\Tests\Fixtures\DummyCommandWithDescription;
+use Symfony\Component\Messenger\Tests\Fixtures\DummyCommandWithDescriptionHandler;
 use Symfony\Component\Messenger\Tests\Fixtures\DummyQuery;
 use Symfony\Component\Messenger\Tests\Fixtures\DummyQueryHandler;
 use Symfony\Component\Messenger\Tests\Fixtures\MultipleBusesMessage;
@@ -41,6 +43,7 @@ class DebugCommandTest extends TestCase
         $command = new DebugCommand([
             'command_bus' => [
                 DummyCommand::class => [[DummyCommandHandler::class, ['option1' => '1', 'option2' => '2']]],
+                DummyCommandWithDescription::class => [[DummyCommandWithDescriptionHandler::class, []]],
                 MultipleBusesMessage::class => [[MultipleBusesMessageHandler::class, []]],
             ],
             'query_bus' => [
@@ -65,8 +68,15 @@ command_bus
  ----------------------------------------------------------------------------------------------------------- 
   Symfony\Component\Messenger\Tests\Fixtures\DummyCommand                                                    
       handled by Symfony\Component\Messenger\Tests\Fixtures\DummyCommandHandler (when option1=1, option2=2)  
+                                                                                                             
+  Used whenever a test needs to show a message with a class description.                                     
+  Symfony\Component\Messenger\Tests\Fixtures\DummyCommandWithDescription                                     
+      handled by Symfony\Component\Messenger\Tests\Fixtures\DummyCommandWithDescriptionHandler               
+                 Used whenever a test needs to show a message handler with a class description.              
+                                                                                                             
   Symfony\Component\Messenger\Tests\Fixtures\MultipleBusesMessage                                            
       handled by Symfony\Component\Messenger\Tests\Fixtures\MultipleBusesMessageHandler                      
+                                                                                                             
  ----------------------------------------------------------------------------------------------------------- 
 
 query_bus
@@ -77,8 +87,10 @@ query_bus
  --------------------------------------------------------------------------------------- 
   Symfony\Component\Messenger\Tests\Fixtures\DummyQuery                                  
       handled by Symfony\Component\Messenger\Tests\Fixtures\DummyQueryHandler            
+                                                                                         
   Symfony\Component\Messenger\Tests\Fixtures\MultipleBusesMessage                        
       handled by Symfony\Component\Messenger\Tests\Fixtures\MultipleBusesMessageHandler  
+                                                                                         
  --------------------------------------------------------------------------------------- 
 
 
@@ -101,8 +113,10 @@ query_bus
  --------------------------------------------------------------------------------------- 
   Symfony\Component\Messenger\Tests\Fixtures\DummyQuery                                  
       handled by Symfony\Component\Messenger\Tests\Fixtures\DummyQueryHandler            
+                                                                                         
   Symfony\Component\Messenger\Tests\Fixtures\MultipleBusesMessage                        
       handled by Symfony\Component\Messenger\Tests\Fixtures\MultipleBusesMessageHandler  
+                                                                                         
  --------------------------------------------------------------------------------------- 
 
 

src/Symfony/Component/Messenger/Tests/Fixtures/DummyCommandWithDescription.php

@@ -0,0 +1,19 @@
+<?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\Messenger\Tests\Fixtures;
+
+/**
+ * Used whenever a test needs to show a message with a class description.
+ */
+class DummyCommandWithDescription
+{
+}

src/Symfony/Component/Messenger/Tests/Fixtures/DummyCommandWithDescriptionHandler.php

@@ -0,0 +1,22 @@
+<?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\Messenger\Tests\Fixtures;
+
+/**
+ * Used whenever a test needs to show a message handler with a class description.
+ */
+class DummyCommandWithDescriptionHandler
+{
+    public function __invoke(DummyCommandWithDescription $command)
+    {
+    }
+}