feature #28970 [FrameworkBundle] make debug:autowiring list useful services and their description (nicolas-grekas)

This PR was merged into the 4.2-dev branch.

Discussion
----------

[FrameworkBundle] make debug:autowiring list useful services and their description

| Q             | A
| ------------- | ---
| Branch?       | 4.2
| Bug fix?      | yes
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | #27207
| License       | MIT
| Doc PR        | -

This PR closes #27207: we don't need "semantics" anymore. 4.2 has everything already to allow us to separate useful services from the other ones: any autowireable *alias* **is** a useful service!
Add autowiring by type + parameter name (#28234) and the story is done: we can easily hint people about which features their bundles provide, without being polluted by for-wiring-only services.

Here is a screenshot running this command(before I excluded the aliases for $cacheApp and $cacheSystem):
![image 3](https://user-images.githubusercontent.com/243674/47437006-f41f4380-d7a7-11e8-9f76-7f23e9193ce8.png)

ping @weaverryan as we drafted that together.
Fixes a few issues found meanwhile.
That should definitely go in 4.2.

Commits
-------

56aab09b01 [FrameworkBundle] make debug:autowiring list useful services and their description

Author: nicolas-grekas

Command/ContainerDebugCommand.php

@@ -261,7 +261,7 @@ private function findServiceIdsContaining(ContainerBuilder $builder, string $nam
     public function filterToServiceTypes($serviceId)
     {
         // filter out things that could not be valid class names
-        if (!preg_match('/^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*+(?:\\\\[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*+)*+$/', $serviceId)) {
+        if (!preg_match('/(?(DEFINE)(?<V>[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*+))^(?&V)(?:\\\\(?&V))*+(?: \$(?&V))?$/', $serviceId)) {
             return false;
         }
 
@@ -270,13 +270,6 @@ public function filterToServiceTypes($serviceId)
             return true;
         }
 
-        try {
-            new \ReflectionClass($serviceId);
-
-            return true;
-        } catch (\ReflectionException $e) {
-            // the service id is not a valid class/interface
-            return false;
-        }
+        return class_exists($serviceId) || interface_exists($serviceId, false);
     }
 }

Command/DebugAutowiringCommand.php

@@ -11,8 +11,10 @@
 
 namespace Symfony\Bundle\FrameworkBundle\Command;
 
+use Symfony\Bundle\FrameworkBundle\Console\Descriptor\Descriptor;
 use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Console\Style\SymfonyStyle;
 
@@ -35,10 +37,11 @@ protected function configure()
         $this
             ->setDefinition(array(
                 new InputArgument('search', InputArgument::OPTIONAL, 'A search filter'),
+                new InputOption('all', null, InputOption::VALUE_NONE, 'Show also services that are not aliased'),
             ))
             ->setDescription('Lists classes/interfaces you can use for autowiring')
             ->setHelp(<<<'EOF'
-The <info>%command.name%</info> command displays all classes and interfaces that
+The <info>%command.name%</info> command displays the classes and interfaces that
 you can use as type-hints for autowiring:
 
   <info>php %command.full_name%</info>
@@ -76,26 +79,39 @@ protected function execute(InputInterface $input, OutputInterface $output)
             }
         }
 
-        asort($serviceIds);
+        uasort($serviceIds, 'strnatcmp');
 
-        $io->title('Autowirable Services');
+        $io->title('Autowirable Types');
         $io->text('The following classes & interfaces can be used as type-hints when autowiring:');
         if ($search) {
             $io->text(sprintf('(only showing classes/interfaces matching <comment>%s</comment>)', $search));
         }
-        $io->newLine();
         $tableRows = array();
         $hasAlias = array();
+        $all = $input->getOption('all');
+        $previousId = '-';
         foreach ($serviceIds as $serviceId) {
+            $text = array();
+            if (0 !== strpos($serviceId, $previousId)) {
+                $text[] = '';
+                if ('' !== $description = Descriptor::getClassDescription($serviceId, $serviceId)) {
+                    if (isset($hasAlias[$serviceId])) {
+                        continue;
+                    }
+                    $text[] = $description;
+                }
+                $previousId = $serviceId.' $';
+            }
+            $serviceLine = sprintf('<fg=yellow>%s</>', $serviceId);
             if ($builder->hasAlias($serviceId)) {
-                $tableRows[] = array(sprintf('<fg=cyan>%s</fg=cyan>', $serviceId));
-                $tableRows[] = array(sprintf('    alias to %s', $builder->getAlias($serviceId)));
-                $hasAlias[(string) $builder->getAlias($serviceId)] = true;
-            } else {
-                $tableRows[$serviceId] = array(sprintf('<fg=cyan>%s</fg=cyan>', $serviceId));
+                $hasAlias[$serviceId] = true;
+                $serviceLine .= ' <fg=cyan>('.$builder->getAlias($serviceId).')</>';
+            } elseif (!$all) {
+                continue;
             }
+            $text[] = $serviceLine;
+            $io->text($text);
         }
-
-        $io->table(array(), array_diff_key($tableRows, $hasAlias));
+        $io->newLine();
     }
 }

Console/Descriptor/Descriptor.php

@@ -289,26 +289,25 @@ protected function sortServiceIds(array $serviceIds)
 
     /**
      * Gets class description from a docblock.
-     *
-     * @param string $class
-     *
-     * @return string
      */
-    protected function getClassDescription($class)
+    public static function getClassDescription(string $class, string &$resolvedClass = null): string
     {
+        $resolvedClass = null;
+
         if (!interface_exists(DocBlockFactoryInterface::class)) {
             return '';
         }
 
         try {
-            $reflectionProperty = new \ReflectionClass($class);
+            $r = new \ReflectionClass($class);
+            $resolvedClass = $r->name;
 
-            if ($docComment = $reflectionProperty->getDocComment()) {
+            if ($docComment = $r->getDocComment()) {
                 return DocBlockFactory::createInstance()
                     ->create($docComment)
                     ->getSummary();
             }
-        } catch (\ReflectionException $e) {
+        } catch (\ReflectionException | \InvalidArgumentException $e) {
         }
 
         return '';

DependencyInjection/FrameworkExtension.php

@@ -1640,8 +1640,10 @@ private function registerCacheConfiguration(array $config, ContainerBuilder $con
                 $pool['adapter'] = '.'.$pool['adapter'].'.inner';
             }
             $definition = new ChildDefinition($pool['adapter']);
-            $container->registerAliasForArgument($name, CacheInterface::class);
-            $container->registerAliasForArgument($name, CacheItemPoolInterface::class);
+            if (!\in_array($name, array('cache.app', 'cache.system'), true)) {
+                $container->registerAliasForArgument($name, CacheInterface::class);
+                $container->registerAliasForArgument($name, CacheItemPoolInterface::class);
+            }
 
             if ($pool['tags']) {
                 if ($config['pools'][$pool['tags']]['tags'] ?? false) {

Tests/Functional/DebugAutowiringCommandTest.php

@@ -30,7 +30,7 @@ public function testBasicFunctionality()
         $tester->run(array('command' => 'debug:autowiring'));
 
         $this->assertContains('Symfony\Component\HttpKernel\HttpKernelInterface', $tester->getDisplay());
-        $this->assertContains('alias to http_kernel', $tester->getDisplay());
+        $this->assertContains('(http_kernel)', $tester->getDisplay());
     }
 
     public function testSearchArgument()