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
+-----
+
+ * Deprecated `RouteCollectionBuilder` in favor of `RoutingConfigurator`.
+ * Added support for a generic loader to `RoutingConfigurator`.
+
 5.0.0
 -----
 

Loader/Configurator/RoutingConfigurator.php

@@ -11,7 +11,9 @@
 
 namespace Symfony\Component\Routing\Loader\Configurator;
 
-use Symfony\Component\Routing\Loader\PhpFileLoader;
+use Symfony\Component\Config\Exception\LoaderLoadException;
+use Symfony\Component\Config\Loader\FileLoader;
+use Symfony\Component\Config\Loader\LoaderInterface;
 use Symfony\Component\Routing\RouteCollection;
 
 /**
@@ -25,7 +27,7 @@ class RoutingConfigurator
     private $path;
     private $file;
 
-    public function __construct(RouteCollection $collection, PhpFileLoader $loader, string $path, string $file)
+    public function __construct(RouteCollection $collection, LoaderInterface $loader, ?string $path, string $file)
     {
         $this->collection = $collection;
         $this->loader = $loader;
@@ -38,9 +40,7 @@ public function __construct(RouteCollection $collection, PhpFileLoader $loader,
      */
     final public function import($resource, string $type = null, bool $ignoreErrors = false, $exclude = null): ImportConfigurator
     {
-        $this->loader->setCurrentDir(\dirname($this->path));
-
-        $imported = $this->loader->import($resource, $type, $ignoreErrors, $this->file, $exclude) ?: [];
+        $imported = $this->load($resource, $type, $ignoreErrors, $exclude) ?: [];
         if (!\is_array($imported)) {
             return new ImportConfigurator($this->collection, $imported);
         }
@@ -57,4 +57,34 @@ final public function collection(string $name = ''): CollectionConfigurator
     {
         return new CollectionConfigurator($this->collection, $name);
     }
+
+    /**
+     * @param string|string[]|null $exclude
+     *
+     * @return RouteCollection|RouteCollection[]|null
+     */
+    private function load($resource, ?string $type, bool $ignoreErrors, $exclude)
+    {
+        $loader = $this->loader;
+
+        if (!$loader->supports($resource, $type)) {
+            if (null === $resolver = $loader->getResolver()) {
+                throw new LoaderLoadException($resource, $this->file, null, null, $type);
+            }
+
+            if (false === $loader = $resolver->resolve($resource, $type)) {
+                throw new LoaderLoadException($resource, $this->file, null, null, $type);
+            }
+        }
+
+        if (!$loader instanceof FileLoader) {
+            return $loader->load($resource, $type);
+        }
+
+        if (null !== $this->path) {
+            $this->loader->setCurrentDir(\dirname($this->path));
+        }
+
+        return $this->loader->import($resource, $type, $ignoreErrors, $this->file, $exclude);
+    }
 }

RouteCollectionBuilder.php

@@ -19,6 +19,8 @@
  * Helps add and import routes into a RouteCollection.
  *
  * @author Ryan Weaver <ryan@knpuniversity.com>
+ *
+ * @deprecated since Symfony 5.1, use RoutingConfigurator instead
  */
 class RouteCollectionBuilder
 {

Tests/RouteCollectionBuilderTest.php

@@ -19,6 +19,9 @@
 use Symfony\Component\Routing\RouteCollection;
 use Symfony\Component\Routing\RouteCollectionBuilder;
 
+/**
+ * @group legacy
+ */
 class RouteCollectionBuilderTest extends TestCase
 {
     public function testImport()