[FrameworkBundle] Auto-generate config/reference.php to assist in writing and discovering app's configuration

Author: nicolas-grekas

CHANGELOG.md

@@ -9,7 +9,7 @@ CHANGELOG
  * Add support of multiple env names in the  `Symfony\Component\Routing\Attribute\Route` attribute
  * Add argument `$parameters` to `RequestContext`'s constructor
  * Handle declaring routes using PHP arrays that follow the same shape as corresponding yaml files
- * Add `RoutesConfig` to help writing PHP configs using yaml-like array-shapes
+ * Add `RoutesReference` to help writing PHP configs using yaml-like array-shapes
  * Deprecate class aliases in the `Annotation` namespace, use attributes instead
  * Deprecate getters and setters in attribute classes in favor of public properties
  * Deprecate accessing the internal scope of the loader in PHP config files, use only its public API instead

Loader/Config/RoutesConfig.php renamed to Loader/Configurator/RoutesReference.php

@@ -9,10 +9,30 @@
  * file that was distributed with this source code.
  */
 
-namespace Symfony\Config;
+namespace Symfony\Component\Routing\Loader\Configurator;
+
+// For the phpdoc to remain compatible with the generation of per-app Routes class,
+// this file should have no "use" statements: all symbols referenced by
+// the phpdoc need to be in the current namespace or be root-scoped.
 
 /**
- * @psalm-type Route = array{
+ * This class provides array-shapes for configuring the routes of an application.
+ *
+ * Example:
+ *
+ *     ```php
+ *     // config/routes.php
+ *     namespace Symfony\Component\Routing\Loader\Configurator;
+ *
+ *     return Routes::config([
+ *         'controllers' => [
+ *             'resource' => 'attributes',
+ *             'type' => 'tagged_services',
+ *         ],
+ *     ]);
+ *     ```
+ *
+ * @psalm-type RouteConfig = array{
  *     path: string|array<string,string>,
  *     controller?: string,
  *     methods?: string|list<string>,
@@ -27,7 +47,7 @@
  *     utf8?: bool,
  *     stateless?: bool,
  * }
- * @psalm-type Import = array{
+ * @psalm-type ImportConfig = array{
  *     resource: string,
  *     type?: string,
  *     exclude?: string|list<string>,
@@ -47,19 +67,21 @@
  *     utf8?: bool,
  *     stateless?: bool,
  * }
- * @psalm-type Alias = array{
+ * @psalm-type AliasConfig = array{
  *     alias: string,
  *     deprecated?: array{package:string, version:string, message?:string},
  * }
- * @psalm-type Routes = array<string, Route|Import|Alias|RoutesConfig|array<string, Route|Import|Alias>>
+ * @psalm-type RoutesConfig = array<string, RouteConfig|ImportConfig|AliasConfig|array<string, RouteConfig|ImportConfig|AliasConfig>>
  */
-class RoutesConfig
+class RoutesReference
 {
     /**
-     * @param Routes $routes
+     * @param RoutesConfig $config
+     *
+     * @psalm-return RoutesConfig
      */
-    public function __construct(
-        public readonly array $routes,
-    ) {
+    public static function config(array $config): array
+    {
+        return $config;
     }
 }

Loader/PhpFileLoader.php

@@ -15,13 +15,10 @@
 use Symfony\Component\Config\Loader\LoaderResolver;
 use Symfony\Component\Config\Resource\FileResource;
 use Symfony\Component\Routing\Exception\InvalidArgumentException;
-use Symfony\Component\Routing\Loader\Configurator\AliasConfigurator;
-use Symfony\Component\Routing\Loader\Configurator\CollectionConfigurator;
-use Symfony\Component\Routing\Loader\Configurator\ImportConfigurator;
-use Symfony\Component\Routing\Loader\Configurator\RouteConfigurator;
+use Symfony\Component\Routing\Loader\Configurator\Routes;
+use Symfony\Component\Routing\Loader\Configurator\RoutesReference;
 use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 use Symfony\Component\Routing\RouteCollection;
-use Symfony\Config\RoutesConfig;
 
 /**
  * PhpFileLoader loads routes from a PHP file.
@@ -42,6 +39,11 @@ public function load(mixed $file, ?string $type = null): RouteCollection
         $path = $this->locator->locate($file);
         $this->setCurrentDir(\dirname($path));
 
+        // Expose RoutesReference::config() as Routes::config()
+        if (!class_exists(Routes::class)) {
+            class_alias(RoutesReference::class, Routes::class);
+        }
+
         // the closure forbids access to the private scope in the included file
         $loader = $this;
         $load = \Closure::bind(static function ($file) use ($loader) {
@@ -66,9 +68,13 @@ public function load(mixed $file, ?string $type = null): RouteCollection
 
         if (\is_object($result) && \is_callable($result)) {
             $collection = $this->callConfigurator($result, $path, $file);
-        } else {
+        } elseif (\is_array($result)) {
             $collection = new RouteCollection();
-            $this->loadRoutes($collection, $result, $path, $file);
+            $loader = new YamlFileLoader($this->locator, $this->env);
+            $loader->setResolver($this->resolver ?? new LoaderResolver([$this]));
+            (new \ReflectionMethod(YamlFileLoader::class, 'loadContent'))->invoke($loader, $collection, $result, $path, $file);
+        } elseif (!($collection = $result) instanceof RouteCollection) {
+            throw new InvalidArgumentException(\sprintf('The return value in config file "%s" is expected to be a RouteCollection, an array or a configurator callable, but got "%s".', $path, get_debug_type($result)));
         }
 
         $collection->addResource(new FileResource($path));
@@ -85,61 +91,10 @@ protected function callConfigurator(callable $callback, string $path, string $fi
     {
         $collection = new RouteCollection();
 
-        $result = $callback(new RoutingConfigurator($collection, $this, $path, $file, $this->env));
-        $this->loadRoutes($collection, $result, $path, $file);
+        $callback(new RoutingConfigurator($collection, $this, $path, $file, $this->env));
 
         return $collection;
     }
-
-    private function loadRoutes(RouteCollection $collection, mixed $routes, string $path, string $file): void
-    {
-        if (null === $routes
-            || $routes instanceof RouteCollection
-            || $routes instanceof AliasConfigurator
-            || $routes instanceof CollectionConfigurator
-            || $routes instanceof ImportConfigurator
-            || $routes instanceof RouteConfigurator
-            || $routes instanceof RoutingConfigurator
-        ) {
-            if ($routes instanceof RouteCollection && $collection !== $routes) {
-                $collection->addCollection($routes);
-            }
-
-            return;
-        }
-
-        if ($routes instanceof RoutesConfig) {
-            $routes = $routes->routes;
-        } elseif (!is_iterable($routes)) {
-            throw new InvalidArgumentException(\sprintf('The return value in config file "%s" is invalid: "%s" given.', $path, get_debug_type($routes)));
-        }
-
-        $loader = new YamlFileLoader($this->locator, $this->env);
-        $loader->setResolver(new LoaderResolver([$this]));
-
-        \Closure::bind(function () use ($collection, $routes, $path, $file) {
-            foreach ($routes as $name => $config) {
-                if (str_starts_with($when = $name, 'when@')) {
-                    if (!$this->env || 'when@'.$this->env !== $name) {
-                        continue;
-                    }
-                    $when .= '" when "@'.$this->env;
-                } elseif (!$config instanceof RoutesConfig) {
-                    $config = [$name => $config];
-                } elseif (!\is_int($name)) {
-                    throw new InvalidArgumentException(\sprintf('Invalid key "%s" returned for the "%s" config builder; none or "when@%%env%%" expected in file "%s".', $name, get_debug_type($config), $path));
-                }
-
-                if ($config instanceof RoutesConfig) {
-                    $config = $config->routes;
-                } elseif (!\is_array($config)) {
-                    throw new InvalidArgumentException(\sprintf('The "%s" key should contain an array in "%s".', $name, $path));
-                }
-
-                $this->loadContent($collection, $config, $path, $file);
-            }
-        }, $loader, YamlFileLoader::class)();
-    }
 }
 
 /**

Tests/Fixtures/array_routes.php

@@ -1,6 +1,8 @@
 <?php
 
-return [
+use Symfony\Component\Routing\Loader\Configurator\Routes;
+
+return Routes::config([
     'a' => ['path' => '/a'],
     'b' => ['path' => '/b', 'methods' => ['GET']],
-];
+]);

Tests/Fixtures/array_when_env.php

@@ -1,8 +1,10 @@
 <?php
 
-return [
+use Symfony\Component\Routing\Loader\Configurator\Routes;
+
+return Routes::config([
     'when@some-env' => [
         'x' => ['path' => '/x'],
     ],
     'a' => ['path' => '/a'],
-];
+]);

Tests/Fixtures/routes_object.php

@@ -374,29 +374,6 @@ public function testLoadsArrayRoutes()
         $this->assertSame(['GET'], $routes->get('b')->getMethods());
     }
 
-    public function testLoadsObjectRoutes()
-    {
-        $loader = new PhpFileLoader(new FileLocator([__DIR__.'/../Fixtures']));
-        $routes = $loader->load('routes_object.php');
-        $this->assertSame('/a', $routes->get('a')->getPath());
-        $this->assertSame('/b', $routes->get('b')->getPath());
-        $this->assertSame(['GET'], $routes->get('b')->getMethods());
-        $this->assertNull($routes->get('c'));
-        $this->assertNull($routes->get('d'));
-
-        $loader = new PhpFileLoader(new FileLocator([__DIR__.'/../Fixtures']), 'dev');
-        $routes = $loader->load('routes_object.php');
-        $this->assertSame('/a', $routes->get('a')->getPath());
-        $this->assertSame('/b', $routes->get('b')->getPath());
-        $this->assertSame('/c', $routes->get('c')->getPath());
-        $this->assertNull($routes->get('d'));
-
-        $loader = new PhpFileLoader(new FileLocator([__DIR__.'/../Fixtures']), 'test');
-        $routes = $loader->load('routes_object.php');
-        $this->assertNull($routes->get('c'));
-        $this->assertSame('/d', $routes->get('d')->getPath());
-    }
-
     public function testWhenEnvWithArray()
     {
         $locator = new FileLocator([__DIR__.'/../Fixtures']);

Tests/Loader/PhpFileLoaderTest.php

@@ -33,10 +33,7 @@
         "symfony/yaml": "<6.4"
     },
     "autoload": {
-        "psr-4": {
-            "Symfony\\Component\\Routing\\": "",
-            "Symfony\\Config\\": "Loader/Config/"
-        },
+        "psr-4": { "Symfony\\Component\\Routing\\": "" },
         "exclude-from-classmap": [
             "/Tests/"
         ]