[DependencyInjection][Routing] Define array-shapes to help writing PHP configs using yaml-like arrays

Author: nicolas-grekas

CHANGELOG.md

@@ -9,6 +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
  * 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

@@ -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\Config;
+
+/**
+ * @psalm-type Route = array{
+ *     path: string|array<string,string>,
+ *     controller?: string,
+ *     methods?: string|list<string>,
+ *     requirements?: array<string,string>,
+ *     defaults?: array<string,mixed>,
+ *     options?: array<string,mixed>,
+ *     host?: string|array<string,string>,
+ *     schemes?: string|list<string>,
+ *     condition?: string,
+ *     locale?: string,
+ *     format?: string,
+ *     utf8?: bool,
+ *     stateless?: bool,
+ * }
+ * @psalm-type Import = array{
+ *     resource: string,
+ *     type?: string,
+ *     exclude?: string|list<string>,
+ *     prefix?: string|array<string,string>,
+ *     name_prefix?: string,
+ *     trailing_slash_on_root?: bool,
+ *     controller?: string,
+ *     methods?: string|list<string>,
+ *     requirements?: array<string,string>,
+ *     defaults?: array<string,mixed>,
+ *     options?: array<string,mixed>,
+ *     host?: string|array<string,string>,
+ *     schemes?: string|list<string>,
+ *     condition?: string,
+ *     locale?: string,
+ *     format?: string,
+ *     utf8?: bool,
+ *     stateless?: bool,
+ * }
+ * @psalm-type Alias = array{
+ *     alias: string,
+ *     deprecated?: array{package:string, version:string, message?:string},
+ * }
+ * @psalm-type Routes = array<string, Route|Import|Alias>
+ */
+class RoutesConfig
+{
+    /**
+     * @param Routes $routes
+     */
+    public function __construct(
+        public readonly array $routes,
+    ) {
+    }
+}

Loader/PhpFileLoader.php

@@ -13,12 +13,14 @@
 
 use Symfony\Component\Config\Loader\FileLoader;
 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\RoutingConfigurator;
 use Symfony\Component\Routing\RouteCollection;
+use Symfony\Config\RoutesConfig;
 
 /**
  * PhpFileLoader loads routes from a PHP file.
@@ -105,38 +107,45 @@ private function loadRoutes(RouteCollection $collection, mixed $routes, string $
             return;
         }
 
-        if (!is_iterable($routes)) {
-            throw new \InvalidArgumentException(\sprintf('The return value in config file "%s" is invalid: "%s" given.', $path, get_debug_type($routes)));
+        if ($routes instanceof RoutesConfig) {
+            $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);
 
         \Closure::bind(function () use ($collection, $routes, $path, $file) {
             foreach ($routes as $name => $config) {
+                $when = $name;
                 if (str_starts_with($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));
+                }
 
-                    foreach ($config as $name => $config) {
-                        $this->validate($config, $name.'" when "@'.$this->env, $path);
-
-                        if (isset($config['resource'])) {
-                            $this->parseImport($collection, $config, $path, $file);
-                        } else {
-                            $this->parseRoute($collection, $name, $config, $path);
-                        }
-                    }
-
-                    continue;
+                if ($config instanceof RoutesConfig) {
+                    $config = $config->routes;
+                } elseif (!is_iterable($config)) {
+                    throw new InvalidArgumentException(\sprintf('The "%s" key should contain an array in "%s".', $name, $path));
                 }
 
-                $this->validate($config, $name, $path);
+                foreach ($config as $name => $config) {
+                    if (str_starts_with($name, 'when@')) {
+                        throw new InvalidArgumentException(\sprintf('A route name cannot start with "when@" in "%s".', $path));
+                    }
+                    $this->validate($config, $when, $path);
 
-                if (isset($config['resource'])) {
-                    $this->parseImport($collection, $config, $path, $file);
-                } else {
-                    $this->parseRoute($collection, $name, $config, $path);
+                    if (isset($config['resource'])) {
+                        $this->parseImport($collection, $config, $path, $file);
+                    } else {
+                        $this->parseRoute($collection, $name, $config, $path);
+                    }
                 }
             }
         }, $loader, $loader::class)();

Tests/Fixtures/routes_object.php

@@ -0,0 +1,13 @@
+<?php
+
+use Symfony\Config\RoutesConfig;
+
+return new RoutesConfig([
+    'a' => [
+        'path' => '/a',
+    ],
+    'b' => [
+        'path' => '/b',
+        'methods' => ['GET'],
+    ],
+]);

Tests/Loader/PhpFileLoaderTest.php

@@ -374,6 +374,15 @@ 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());
+    }
+
     public function testWhenEnvWithArray()
     {
         $locator = new FileLocator([__DIR__.'/../Fixtures']);

composer.json

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