feature symfony#61492 [FrameworkBundle][Routing] Auto-register routes from attributes found on controller services (nicolas-grekas)

This PR was merged into the 7.4 branch.

Discussion
----------

[FrameworkBundle][Routing] Auto-register routes from attributes found on controller services

| Q             | A
| ------------- | ---
| Branch?       | 7.4
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        | symfony#60946
| License       | MIT

Currently, controllers have to be put in predetermined directories for their route attributes to be parsed.

This PR enables auto-registration of controllers based on their service definition, independently of where they're located in the app - which means they could be put anywhere now.

config/routes.yaml before:
```yaml
controllers:
    resource:
        path: ../src/Controller/
        namespace: App\Controller
    type: attribute
```

config/routes.yaml after:
```yaml
controllers:
    resource: attributes
    type: tagged_services
```

Recipe update at symfony/recipes#1448

Commits
-------

d0bbf04 [Routing][FrameworkBundle] Auto-register routes from attributes found on controller services

Author: fabpot

src/Symfony/Bundle/FrameworkBundle/CHANGELOG.md

@@ -4,6 +4,7 @@ CHANGELOG
 7.4
 ---
 
+ * Auto-register routes from attributes found on controller services
  * Add `ControllerHelper`; the helpers from AbstractController as a standalone service
  * Allow using their name without added suffix when using `#[Target]` for custom services
  * Deprecate `Symfony\Bundle\FrameworkBundle\Console\Application::add()` in favor of `Symfony\Bundle\FrameworkBundle\Console\Application::addCommand()`

src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php

@@ -172,6 +172,7 @@
 use Symfony\Component\RemoteEvent\Attribute\AsRemoteEventConsumer;
 use Symfony\Component\RemoteEvent\RemoteEvent;
 use Symfony\Component\Routing\Attribute\Route;
+use Symfony\Component\Routing\Loader\AttributeServicesLoader;
 use Symfony\Component\Scheduler\Attribute\AsCronTask;
 use Symfony\Component\Scheduler\Attribute\AsPeriodicTask;
 use Symfony\Component\Scheduler\Attribute\AsSchedule;
@@ -768,7 +769,7 @@ public function load(array $configs, ContainerBuilder $container): void
             $definition->addTag('controller.service_arguments');
         });
         $container->registerAttributeForAutoconfiguration(Route::class, static function (ChildDefinition $definition, Route $attribute, \ReflectionClass|\ReflectionMethod $reflection): void {
-            $definition->addTag('controller.service_arguments');
+            $definition->addTag('controller.service_arguments')->addTag('routing.controller');
         });
         $container->registerAttributeForAutoconfiguration(AsRemoteEventConsumer::class, static function (ChildDefinition $definition, AsRemoteEventConsumer $attribute): void {
             $definition->addTag('remote_event.consumer', ['consumer' => $attribute->name]);
@@ -1307,6 +1308,10 @@ private function registerRouterConfiguration(array $config, ContainerBuilder $co
 
         $loader->load('routing.php');
 
+        if (!class_exists(AttributeServicesLoader::class)) {
+            $container->removeDefinition('routing.loader.attribute.services');
+        }
+
         if ($config['utf8']) {
             $container->getDefinition('routing.loader')->replaceArgument(1, ['utf8' => true]);
         }

src/Symfony/Bundle/FrameworkBundle/FrameworkBundle.php

@@ -61,6 +61,7 @@
 use Symfony\Component\PropertyInfo\DependencyInjection\PropertyInfoConstructorPass;
 use Symfony\Component\PropertyInfo\DependencyInjection\PropertyInfoPass;
 use Symfony\Component\Routing\DependencyInjection\AddExpressionLanguageProvidersPass;
+use Symfony\Component\Routing\DependencyInjection\RoutingControllerPass;
 use Symfony\Component\Routing\DependencyInjection\RoutingResolverPass;
 use Symfony\Component\Runtime\SymfonyRuntime;
 use Symfony\Component\Scheduler\DependencyInjection\AddScheduleMessengerPass;
@@ -146,6 +147,7 @@ public function build(ContainerBuilder $container): void
         $container->addCompilerPass(new RegisterControllerArgumentLocatorsPass());
         $container->addCompilerPass(new RemoveEmptyControllerArgumentLocatorsPass(), PassConfig::TYPE_BEFORE_REMOVING);
         $container->addCompilerPass(new RoutingResolverPass());
+        $this->addCompilerPassIfExists($container, RoutingControllerPass::class);
         $this->addCompilerPassIfExists($container, DataCollectorTranslatorPass::class);
         $container->addCompilerPass(new ProfilerPass());
         // must be registered before removing private services as some might be listeners/subscribers

src/Symfony/Bundle/FrameworkBundle/Resources/config/routing.php

@@ -26,6 +26,7 @@
 use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
 use Symfony\Component\Routing\Loader\AttributeDirectoryLoader;
 use Symfony\Component\Routing\Loader\AttributeFileLoader;
+use Symfony\Component\Routing\Loader\AttributeServicesLoader;
 use Symfony\Component\Routing\Loader\ContainerLoader;
 use Symfony\Component\Routing\Loader\DirectoryLoader;
 use Symfony\Component\Routing\Loader\GlobFileLoader;
@@ -98,6 +99,12 @@
             ])
             ->tag('routing.loader', ['priority' => -10])
 
+        ->set('routing.loader.attribute.services', AttributeServicesLoader::class)
+            ->args([
+                abstract_arg('classes tagged with "routing.controller"'),
+            ])
+            ->tag('routing.loader', ['priority' => -10])
+
         ->set('routing.loader.attribute.directory', AttributeDirectoryLoader::class)
             ->args([
                 service('file_locator'),

src/Symfony/Bundle/FrameworkBundle/Tests/Routing/AttributeRouteControllerLoaderTest.php

@@ -0,0 +1,41 @@
+<?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\Bundle\FrameworkBundle\Tests\Routing;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Bundle\FrameworkBundle\Routing\AttributeRouteControllerLoader;
+use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\InvokableController;
+use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\MethodActionControllers;
+
+class AttributeRouteControllerLoaderTest extends TestCase
+{
+    public function testConfigureRouteSetsControllerForInvokable()
+    {
+        $loader = new AttributeRouteControllerLoader();
+        $collection = $loader->load(InvokableController::class);
+
+        $route = $collection->get('lol');
+        $this->assertSame(InvokableController::class, $route->getDefault('_controller'));
+    }
+
+    public function testConfigureRouteSetsControllerForMethod()
+    {
+        $loader = new AttributeRouteControllerLoader();
+        $collection = $loader->load(MethodActionControllers::class);
+
+        $put = $collection->get('put');
+        $post = $collection->get('post');
+
+        $this->assertSame(MethodActionControllers::class.'::put', $put->getDefault('_controller'));
+        $this->assertSame(MethodActionControllers::class.'::post', $post->getDefault('_controller'));
+    }
+}

src/Symfony/Component/Routing/CHANGELOG.md

@@ -4,6 +4,7 @@ CHANGELOG
 7.4
 ---
 
+ * Add `AttributeServicesLoader` and `RoutingControllerPass` to auto-register routes from attributes on services
  * Allow query-specific parameters in `UrlGenerator` using `_query`
  * Add support of multiple env names in the  `Symfony\Component\Routing\Attribute\Route` attribute
  * Add argument `$parameters` to `RequestContext`'s constructor

src/Symfony/Component/Routing/DependencyInjection/RoutingControllerPass.php

@@ -0,0 +1,40 @@
+<?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\Routing\DependencyInjection;
+
+use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
+use Symfony\Component\DependencyInjection\Compiler\PriorityTaggedServiceTrait;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+
+/**
+ * @author Nicolas Grekas <p@tchwork.com>
+ */
+class RoutingControllerPass implements CompilerPassInterface
+{
+    use PriorityTaggedServiceTrait;
+
+    public function process(ContainerBuilder $container): void
+    {
+        if (!$container->hasDefinition('routing.loader.attribute.services')) {
+            return;
+        }
+
+        $resolve = $container->getParameterBag()->resolveValue(...);
+        $taggedClasses = [];
+        foreach ($this->findAndSortTaggedServices('routing.controller', $container) as $id) {
+            $taggedClasses[$resolve($container->getDefinition($id)->getClass())] = true;
+        }
+
+        $container->getDefinition('routing.loader.attribute.services')
+            ->replaceArgument(0, array_keys($taggedClasses));
+    }
+}

src/Symfony/Component/Routing/Loader/AttributeServicesLoader.php

@@ -0,0 +1,47 @@
+<?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\Routing\Loader;
+
+use Symfony\Component\Config\Loader\Loader;
+use Symfony\Component\Routing\RouteCollection;
+
+/**
+ * Loads routes from a list of tagged classes by delegating to the attribute class loader.
+ *
+ * @author Nicolas Grekas <p@tchwork.com>
+ */
+class AttributeServicesLoader extends Loader
+{
+    /**
+     * @param class-string[] $taggedClasses
+     */
+    public function __construct(
+        private array $taggedClasses = [],
+    ) {
+    }
+
+    public function load(mixed $resource, ?string $type = null): RouteCollection
+    {
+        $collection = new RouteCollection();
+
+        foreach ($this->taggedClasses as $class) {
+            $collection->addCollection($this->import($class, 'attribute'));
+        }
+
+        return $collection;
+    }
+
+    public function supports(mixed $resource, ?string $type = null): bool
+    {
+        return 'tagged_services' === $type && 'attributes' === $resource;
+    }
+}

src/Symfony/Component/Routing/Tests/DependencyInjection/RoutingControllerPassTest.php

@@ -0,0 +1,54 @@
+<?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\Routing\Tests\DependencyInjection;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Definition;
+use Symfony\Component\Routing\DependencyInjection\RoutingControllerPass;
+
+class RoutingControllerPassTest extends TestCase
+{
+    public function testProcessInjectsTaggedControllerClassesOrderedAndUnique()
+    {
+        $container = new ContainerBuilder();
+        $container->setParameter('ctrl_a.class', CtrlA::class);
+
+        $container->register('routing.loader.attribute.services', \stdClass::class)
+            ->setArguments([null]);
+
+        $container->register('ctrl_a', '%ctrl_a.class%')->addTag('routing.controller', ['priority' => 10]);
+        $container->register('ctrl_b', CtrlB::class)->addTag('routing.controller', ['priority' => 20]);
+        $container->register('ctrl_c', CtrlC::class)->addTag('routing.controller', ['priority' => -5]);
+
+        (new RoutingControllerPass())->process($container);
+
+        $this->assertSame([
+            CtrlB::class,
+            CtrlA::class,
+            CtrlC::class,
+        ], $container->getDefinition('routing.loader.attribute.services')->getArgument(0));
+    }
+
+    public function testProcessWithNoTaggedControllersSetsEmptyList()
+    {
+        $container = new ContainerBuilder();
+
+        $loaderDef = new Definition(\stdClass::class);
+        $loaderDef->setArguments([['preexisting']]);
+        $container->setDefinition('routing.loader.attribute.services', $loaderDef);
+
+        (new RoutingControllerPass())->process($container);
+
+        $this->assertSame([], $container->getDefinition('routing.loader.attribute.services')->getArgument(0));
+    }
+}

src/Symfony/Component/Routing/Tests/Loader/AttributeServicesLoaderTest.php

@@ -0,0 +1,65 @@
+<?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\Routing\Tests\Loader;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Config\Loader\LoaderResolver;
+use Symfony\Component\Routing\Loader\AttributeServicesLoader;
+use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\ActionPathController;
+use Symfony\Component\Routing\Tests\Fixtures\AttributeFixtures\MethodActionControllers;
+use Symfony\Component\Routing\Tests\Fixtures\TraceableAttributeClassLoader;
+
+class AttributeServicesLoaderTest extends TestCase
+{
+    public function testSupports()
+    {
+        $loader = new AttributeServicesLoader();
+
+        $this->assertFalse($loader->supports('attributes', null));
+        $this->assertFalse($loader->supports('attributes', 'attribute'));
+        $this->assertFalse($loader->supports('other', 'tagged_services'));
+        $this->assertTrue($loader->supports('attributes', 'tagged_services'));
+    }
+
+    public function testDelegatesToAttributeLoaderAndMergesCollections()
+    {
+        $attributeLoader = new TraceableAttributeClassLoader();
+
+        $servicesLoader = new AttributeServicesLoader([
+            ActionPathController::class,
+            MethodActionControllers::class,
+        ]);
+
+        $resolver = new LoaderResolver([
+            $attributeLoader,
+            $servicesLoader,
+        ]);
+
+        $attributeLoader->setResolver($resolver);
+        $servicesLoader->setResolver($resolver);
+
+        $collection = $servicesLoader->load('attributes', 'tagged_services');
+
+        $this->assertArrayHasKey('action', $collection->all());
+        $this->assertArrayHasKey('put', $collection->all());
+        $this->assertArrayHasKey('post', $collection->all());
+
+        $this->assertSame(['/path'], [$collection->get('action')->getPath()]);
+        $this->assertSame('/the/path', $collection->get('put')->getPath());
+        $this->assertSame('/the/path', $collection->get('post')->getPath());
+
+        $this->assertSame([
+            ActionPathController::class,
+            MethodActionControllers::class,
+        ], $attributeLoader->foundClasses);
+    }
+}