feature #32937 [Routing] Deprecate RouteCollectionBuilder (vudaltsov)

This PR was squashed before being merged into the 5.1-dev branch (closes #32937).

Discussion
----------

[Routing] Deprecate RouteCollectionBuilder

| Q             | A
| ------------- | ---
| Branch?       | 5.1
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | yes
| Tests pass?   | yes
| Fixed tickets | #32240
| License       | MIT
| Doc PR        | symfony/symfony-docs#12688
| Recipe PR | symfony/recipes#690

A lot to be done here after the implementation is accepted:
- [x] finish deprecations in the MicroKernelTrait
- [x] deprecate the class
- [x] mention in the CHANGELOG file
- [x] mention in the UPGRADE file
- [x] mark tests as legacy
- [x] add a doc PR
- [x] update the recipe

Ping @Tobion , @nicolas-grekas .

Commits
-------

e641cbdd46 [Routing] Deprecate RouteCollectionBuilder

Author: fabpot

CHANGELOG.md

@@ -1,6 +1,12 @@
 CHANGELOG
 =========
 
+5.1.0
+-----
+
+ * Marked `MicroKernelTrait::configureRoutes()` as `@internal` and `@final`.
+ * Deprecated not overriding `MicroKernelTrait::configureRouting()`.
+
 5.0.0
 -----
 

Kernel/MicroKernelTrait.php

@@ -14,6 +14,7 @@
 use Symfony\Component\Config\Loader\LoaderInterface;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 use Symfony\Component\Routing\RouteCollectionBuilder;
 
 /**
@@ -29,8 +30,28 @@ trait MicroKernelTrait
      *
      *     $routes->import('config/routing.yml');
      *     $routes->add('/admin', 'App\Controller\AdminController::dashboard', 'admin_dashboard');
+     *
+     * @final since Symfony 5.1, override configureRouting() instead
+     *
+     * @internal since Symfony 5.1, use configureRouting() instead
+     */
+    protected function configureRoutes(RouteCollectionBuilder $routes)
+    {
+    }
+
+    /**
+     * Adds or imports routes into your application.
+     *
+     *     $routes->import($this->getProjectDir().'/config/*.{yaml,php}');
+     *     $routes
+     *         ->add('admin_dashboard', '/admin')
+     *         ->controller('App\Controller\AdminController::dashboard')
+     *     ;
      */
-    abstract protected function configureRoutes(RouteCollectionBuilder $routes);
+    protected function configureRouting(RoutingConfigurator $routes): void
+    {
+        @trigger_error(sprintf('Not overriding the "%s()" method is deprecated since Symfony 5.1 and will trigger a fatal error in 6.0.', __METHOD__), E_USER_DEPRECATED);
+    }
 
     /**
      * Configures the container.
@@ -91,7 +112,15 @@ public function loadRoutes(LoaderInterface $loader)
     {
         $routes = new RouteCollectionBuilder($loader);
         $this->configureRoutes($routes);
+        $collection = $routes->build();
+
+        if (0 !== \count($collection)) {
+            @trigger_error(sprintf('Adding routes via the "%s:configureRoutes()" method is deprecated since Symfony 5.1 and will have no effect in 6.0; use "configureRouting()" instead.', self::class), E_USER_DEPRECATED);
+        }
+
+        $file = (new \ReflectionObject($this))->getFileName();
+        $this->configureRouting(new RoutingConfigurator($collection, $loader, null, $file));
 
-        return $routes->build();
+        return $collection;
     }
 }

Tests/Kernel/ConcreteMicroKernel.php

@@ -22,7 +22,7 @@
 use Symfony\Component\HttpKernel\Event\ExceptionEvent;
 use Symfony\Component\HttpKernel\Kernel;
 use Symfony\Component\HttpKernel\KernelEvents;
-use Symfony\Component\Routing\RouteCollectionBuilder;
+use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
 class ConcreteMicroKernel extends Kernel implements EventSubscriberInterface
 {
@@ -80,10 +80,10 @@ public function __destruct()
         $fs->remove($this->cacheDir);
     }
 
-    protected function configureRoutes(RouteCollectionBuilder $routes)
+    protected function configureRouting(RoutingConfigurator $routes): void
     {
-        $routes->add('/', 'kernel::halloweenAction');
-        $routes->add('/danger', 'kernel::dangerousAction');
+        $routes->add('halloween', '/')->controller('kernel::halloweenAction');
+        $routes->add('danger', '/danger')->controller('kernel::dangerousAction');
     }
 
     protected function configureContainer(ContainerBuilder $c, LoaderInterface $loader)

Tests/Kernel/MicroKernelTraitTest.php

@@ -19,6 +19,18 @@
 
 class MicroKernelTraitTest extends TestCase
 {
+    /**
+     * @group legacy
+     * @expectedDeprecation Adding routes via the "Symfony\Bundle\FrameworkBundle\Tests\Kernel\MicroKernelWithConfigureRoutes:configureRoutes()" method is deprecated since Symfony 5.1 and will have no effect in 6.0; use "configureRouting()" instead.
+     * @expectedDeprecation Not overriding the "Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait::configureRouting()" method is deprecated since Symfony 5.1 and will trigger a fatal error in 6.0.
+     */
+    public function testConfigureRoutingDeprecated()
+    {
+        $kernel = new MicroKernelWithConfigureRoutes('test', false);
+        $kernel->boot();
+        $kernel->handle(Request::create('/'));
+    }
+
     public function test()
     {
         $kernel = new ConcreteMicroKernel('test', false);

Tests/Kernel/MicroKernelWithConfigureRoutes.php

@@ -0,0 +1,74 @@
+<?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\Kernel;
+
+use Psr\Log\NullLogger;
+use Symfony\Bundle\FrameworkBundle\FrameworkBundle;
+use Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait;
+use Symfony\Component\Config\Loader\LoaderInterface;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\Filesystem\Filesystem;
+use Symfony\Component\HttpKernel\Kernel;
+use Symfony\Component\Routing\RouteCollectionBuilder;
+
+class MicroKernelWithConfigureRoutes extends Kernel
+{
+    use MicroKernelTrait;
+
+    private $cacheDir;
+
+    public function registerBundles(): iterable
+    {
+        return [
+            new FrameworkBundle(),
+        ];
+    }
+
+    public function getCacheDir(): string
+    {
+        return $this->cacheDir = sys_get_temp_dir().'/sf_micro_kernel_with_configured_routes';
+    }
+
+    public function getLogDir(): string
+    {
+        return $this->cacheDir;
+    }
+
+    public function __sleep(): array
+    {
+        throw new \BadMethodCallException('Cannot serialize '.__CLASS__);
+    }
+
+    public function __wakeup()
+    {
+        throw new \BadMethodCallException('Cannot unserialize '.__CLASS__);
+    }
+
+    public function __destruct()
+    {
+        $fs = new Filesystem();
+        $fs->remove($this->cacheDir);
+    }
+
+    protected function configureRoutes(RouteCollectionBuilder $routes)
+    {
+        $routes->add('/', 'kernel::halloweenAction');
+    }
+
+    protected function configureContainer(ContainerBuilder $c, LoaderInterface $loader)
+    {
+        $c->register('logger', NullLogger::class);
+        $c->loadFromExtension('framework', [
+            'secret' => '$ecret',
+        ]);
+    }
+}

composer.json

@@ -26,7 +26,7 @@
         "symfony/polyfill-mbstring": "~1.0",
         "symfony/filesystem": "^4.4|^5.0",
         "symfony/finder": "^4.4|^5.0",
-        "symfony/routing": "^5.0"
+        "symfony/routing": "^5.1"
     },
     "require-dev": {
         "doctrine/annotations": "~1.7",