feature #26143 [Routing] Implement i18n routing (frankdejonge, nicolas-grekas)

This PR was merged into the 4.1-dev branch.

Discussion
----------

[Routing]  Implement i18n routing

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      |no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | N/A
| License       | MIT

This PR introduces support for I18N routing into core. This is a port from a bundle I've made recently, now merged into the default implementation. While it's ok to have this as a bundle, it was suggested by @nicolas-grekas to create a PR for this so it can be included into the core.

## New usages

### YAML

```yaml
contact:
    controller: ContactController::formAction
    path:
        en: /send-us-an-email
        nl: /stuur-ons-een-email
```

Will be effectively the same as declaring:

```yaml
contact.en:
    controller: ContactController::formAction
    path: /send-us-an-email
    defaults:
        _locale: en

contact.nl:
    controller: ContactController::formAction
    path: /stuur-ons-een-email
    defaults:
        _locale: nl
```

### Annotation usage:

```php
<?php

use Symfony\Component\Routing\Annotation\Route;

class ContactController
{
    /**
     * @route({"en": "/send-us-an-email", "nl": "/stuur-ons-een-email"}, name="contact")
     */
    public function formAction()
    {

    }
}

/**
 * @route("/contact")
 */
class PrefixedContactController
{
    /**
     * @route({"en": "/send-us-an-email", "nl": "/stuur-ons-een-email"}, name="contact")
     */
    public function formAction()
    {

    }
}
```

### Route generation

```php
<?php
/** @var UrlGeneratorInterface $urlGenerator */
$urlWithCurrentLocale = $urlGenerator->generate('contact');
$urlWithSpecifiedLocale = $urlGenerator->generate('contact', ['_locale' => 'nl']);
```

Route generation is based on your request locale. When not available it falls back on a configured default. This way of route generation means you have a "route locale switcher" out of the box, but generate the current route with another locale for most cases.

## Advantages

Having i18n routes defined like this has some advantages:

* Less error prone.
* No need to keep `requirements` or `defaults` in sync with other definitions.
* No need to `{_locale}` in the path (bad for route matching performance).
* Better developer experience.

### Next steps

I've ported all the things the bundle supported, before moving on I'd like to discuss this first in order not to waste our collective time. This initial PR should give a clear enough picture to see what/how/why this is done.

If and when accepted I/we can move forward to implement the XML loader and @nicolas-grekas mentioned there should be a `Configurator` implemented for this as well. He opted to help with this (for which I'm very thankful).

- [x] Yaml Loader
- [x] Annotation Loader
- [x] XML Loader
- [x] PHP Loader?
- [ ] Documentation

Commits
-------

4ae66dc [Routing] Handle "_canonical_route"
e32c414 [Routing] Implement i18n routing

Author: nicolas-grekas

Annotation/Route.php

@@ -22,6 +22,7 @@
 class Route
 {
     private $path;
+    private $locales = array();
     private $name;
     private $requirements = array();
     private $options = array();
@@ -38,11 +39,20 @@ class Route
      */
     public function __construct(array $data)
     {
+        if (isset($data['locales'])) {
+            throw new \BadMethodCallException(sprintf('Unknown property "locales" on annotation "%s".', get_class($this)));
+        }
+
         if (isset($data['value'])) {
-            $data['path'] = $data['value'];
+            $data[is_array($data['value']) ? 'locales' : 'path'] = $data['value'];
             unset($data['value']);
         }
 
+        if (isset($data['path']) && is_array($data['path'])) {
+            $data['locales'] = $data['path'];
+            unset($data['path']);
+        }
+
         foreach ($data as $key => $value) {
             $method = 'set'.str_replace('_', '', $key);
             if (!method_exists($this, $method)) {
@@ -62,6 +72,16 @@ public function getPath()
         return $this->path;
     }
 
+    public function setLocales(array $locales)
+    {
+        $this->locales = $locales;
+    }
+
+    public function getLocales(): array
+    {
+        return $this->locales;
+    }
+
     public function setHost($pattern)
     {
         $this->host = $pattern;

Generator/Dumper/PhpGeneratorDumper.php

@@ -54,11 +54,13 @@ public function dump(array $options = array())
 class {$options['class']} extends {$options['base_class']}
 {
     private static \$declaredRoutes;
+    private \$defaultLocale;
 
-    public function __construct(RequestContext \$context, LoggerInterface \$logger = null)
+    public function __construct(RequestContext \$context, LoggerInterface \$logger = null, string \$defaultLocale = null)
     {
         \$this->context = \$context;
         \$this->logger = \$logger;
+        \$this->defaultLocale = \$defaultLocale;
         if (null === self::\$declaredRoutes) {
             self::\$declaredRoutes = {$this->generateDeclaredRoutes()};
         }
@@ -107,7 +109,14 @@ private function generateGenerateMethod()
         return <<<'EOF'
     public function generate($name, $parameters = array(), $referenceType = self::ABSOLUTE_PATH)
     {
-        if (!isset(self::$declaredRoutes[$name])) {
+        $locale = $parameters['_locale']
+            ?? $this->context->getParameter('_locale')
+            ?: $this->defaultLocale;
+
+        if (null !== $locale && (self::$declaredRoutes[$name.'.'.$locale][1]['_canonical_route'] ?? null) === $name) {
+            unset($parameters['_locale']);
+            $name .= '.'.$locale;
+        } elseif (!isset(self::$declaredRoutes[$name])) {
             throw new RouteNotFoundException(sprintf('Unable to generate a URL for the named route "%s" as such route does not exist.', $name));
         }
 

Generator/UrlGenerator.php

@@ -37,6 +37,8 @@ class UrlGenerator implements UrlGeneratorInterface, ConfigurableRequirementsInt
 
     protected $logger;
 
+    private $defaultLocale;
+
     /**
      * This array defines the characters (besides alphanumeric ones) that will not be percent-encoded in the path segment of the generated URL.
      *
@@ -65,11 +67,12 @@ class UrlGenerator implements UrlGeneratorInterface, ConfigurableRequirementsInt
         '%7C' => '|',
     );
 
-    public function __construct(RouteCollection $routes, RequestContext $context, LoggerInterface $logger = null)
+    public function __construct(RouteCollection $routes, RequestContext $context, LoggerInterface $logger = null, string $defaultLocale = null)
     {
         $this->routes = $routes;
         $this->context = $context;
         $this->logger = $logger;
+        $this->defaultLocale = $defaultLocale;
     }
 
     /**
@@ -109,7 +112,13 @@ public function isStrictRequirements()
      */
     public function generate($name, $parameters = array(), $referenceType = self::ABSOLUTE_PATH)
     {
-        if (null === $route = $this->routes->get($name)) {
+        $locale = $parameters['_locale']
+            ?? $this->context->getParameter('_locale')
+            ?: $this->defaultLocale;
+
+        if (null !== $locale && null !== ($route = $this->routes->get($name.'.'.$locale)) && $route->getDefault('_canonical_route') === $name) {
+            unset($parameters['_locale']);
+        } elseif (null === $route = $this->routes->get($name)) {
             throw new RouteNotFoundException(sprintf('Unable to generate a URL for the named route "%s" as such route does not exist.', $name));
         }
 

Loader/AnnotationClassLoader.php

@@ -13,6 +13,7 @@
 
 use Doctrine\Common\Annotations\Reader;
 use Symfony\Component\Config\Resource\FileResource;
+use Symfony\Component\Routing\Annotation\Route as RouteAnnotation;
 use Symfony\Component\Routing\Route;
 use Symfony\Component\Routing\RouteCollection;
 use Symfony\Component\Config\Loader\LoaderInterface;
@@ -119,9 +120,11 @@ public function load($class, $type = null)
             }
         }
 
+        /** @var $annot RouteAnnotation */
         if (0 === $collection->count() && $class->hasMethod('__invoke') && $annot = $this->reader->getClassAnnotation($class, $this->routeAnnotationClass)) {
-            $globals['path'] = '';
+            $globals['path'] = null;
             $globals['name'] = '';
+            $globals['locales'] = array();
             $this->addRoute($collection, $annot, $globals, $class, $class->getMethod('__invoke'));
         }
 
@@ -137,11 +140,6 @@ protected function addRoute(RouteCollection $collection, $annot, $globals, \Refl
         $name = $globals['name'].$name;
 
         $defaults = array_replace($globals['defaults'], $annot->getDefaults());
-        foreach ($method->getParameters() as $param) {
-            if (false !== strpos($globals['path'].$annot->getPath(), sprintf('{%s}', $param->getName())) && !isset($defaults[$param->getName()]) && $param->isDefaultValueAvailable()) {
-                $defaults[$param->getName()] = $param->getDefaultValue();
-            }
-        }
         $requirements = array_replace($globals['requirements'], $annot->getRequirements());
         $options = array_replace($globals['options'], $annot->getOptions());
         $schemes = array_merge($globals['schemes'], $annot->getSchemes());
@@ -157,11 +155,57 @@ protected function addRoute(RouteCollection $collection, $annot, $globals, \Refl
             $condition = $globals['condition'];
         }
 
-        $route = $this->createRoute($globals['path'].$annot->getPath(), $defaults, $requirements, $options, $host, $schemes, $methods, $condition);
+        $path = $annot->getLocales() ?: $annot->getPath();
+        $prefix = $globals['locales'] ?: $globals['path'];
+        $paths = array();
 
-        $this->configureRoute($route, $class, $method, $annot);
+        if (\is_array($path)) {
+            if (!\is_array($prefix)) {
+                foreach ($path as $locale => $localePath) {
+                    $paths[$locale] = $prefix.$localePath;
+                }
+            } elseif ($missing = array_diff_key($prefix, $path)) {
+                throw new \LogicException(sprintf('Route to "%s" is missing paths for locale(s) "%s".', $class->name.'::'.$method->name, implode('", "', array_keys($missing))));
+            } else {
+                foreach ($path as $locale => $localePath) {
+                    if (!isset($prefix[$locale])) {
+                        throw new \LogicException(sprintf('Route to "%s" with locale "%s" is missing a corresponding prefix in class "%s".', $method->name, $locale, $class->name));
+                    }
+
+                    $paths[$locale] = $prefix[$locale].$localePath;
+                }
+            }
+        } elseif (\is_array($prefix)) {
+            foreach ($prefix as $locale => $localePrefix) {
+                $paths[$locale] = $localePrefix.$path;
+            }
+        } else {
+            $paths[] = $prefix.$path;
+        }
 
-        $collection->add($name, $route);
+        foreach ($method->getParameters() as $param) {
+            if (isset($defaults[$param->name]) || !$param->isDefaultValueAvailable()) {
+                continue;
+            }
+            foreach ($paths as $locale => $path) {
+                if (false !== strpos($path, sprintf('{%s}', $param->name))) {
+                    $defaults[$param->name] = $param->getDefaultValue();
+                    break;
+                }
+            }
+        }
+
+        foreach ($paths as $locale => $path) {
+            $route = $this->createRoute($path, $defaults, $requirements, $options, $host, $schemes, $methods, $condition);
+            $this->configureRoute($route, $class, $method, $annot);
+            if (0 !== $locale) {
+                $route->setDefault('_locale', $locale);
+                $route->setDefault('_canonical_route', $name);
+                $collection->add($name.'.'.$locale, $route);
+            } else {
+                $collection->add($name, $route);
+            }
+        }
     }
 
     /**
@@ -208,7 +252,8 @@ protected function getDefaultRouteName(\ReflectionClass $class, \ReflectionMetho
     protected function getGlobals(\ReflectionClass $class)
     {
         $globals = array(
-            'path' => '',
+            'path' => null,
+            'locales' => array(),
             'requirements' => array(),
             'options' => array(),
             'defaults' => array(),
@@ -228,6 +273,8 @@ protected function getGlobals(\ReflectionClass $class)
                 $globals['path'] = $annot->getPath();
             }
 
+            $globals['locales'] = $annot->getLocales();
+
             if (null !== $annot->getRequirements()) {
                 $globals['requirements'] = $annot->getRequirements();
             }

Loader/Configurator/CollectionConfigurator.php

@@ -24,30 +24,25 @@ class CollectionConfigurator
 
     private $parent;
     private $parentConfigurator;
+    private $parentPrefixes;
 
-    public function __construct(RouteCollection $parent, string $name, self $parentConfigurator = null)
+    public function __construct(RouteCollection $parent, string $name, self $parentConfigurator = null, array $parentPrefixes = null)
     {
         $this->parent = $parent;
         $this->name = $name;
         $this->collection = new RouteCollection();
         $this->route = new Route('');
         $this->parentConfigurator = $parentConfigurator; // for GC control
+        $this->parentPrefixes = $parentPrefixes;
     }
 
     public function __destruct()
     {
-        $this->collection->addPrefix(rtrim($this->route->getPath(), '/'));
-        $this->parent->addCollection($this->collection);
-    }
-
-    /**
-     * Adds a route.
-     */
-    final public function add(string $name, string $path): RouteConfigurator
-    {
-        $this->collection->add($this->name.$name, $route = clone $this->route);
+        if (null === $this->prefixes) {
+            $this->collection->addPrefix($this->route->getPath());
+        }
 
-        return new RouteConfigurator($this->collection, $route->setPath($path), $this->name, $this);
+        $this->parent->addCollection($this->collection);
     }
 
     /**
@@ -57,18 +52,44 @@ final public function add(string $name, string $path): RouteConfigurator
      */
     final public function collection($name = '')
     {
-        return new self($this->collection, $this->name.$name, $this);
+        return new self($this->collection, $this->name.$name, $this, $this->prefixes);
     }
 
     /**
      * Sets the prefix to add to the path of all child routes.
      *
+     * @param string|array $prefix the prefix, or the localized prefixes
+     *
      * @return $this
      */
-    final public function prefix(string $prefix)
+    final public function prefix($prefix)
     {
-        $this->route->setPath($prefix);
+        if (\is_array($prefix)) {
+            if (null === $this->parentPrefixes) {
+                // no-op
+            } elseif ($missing = array_diff_key($this->parentPrefixes, $prefix)) {
+                throw new \LogicException(sprintf('Collection "%s" is missing prefixes for locale(s) "%s".', $this->name, implode('", "', array_keys($missing))));
+            } else {
+                foreach ($prefix as $locale => $localePrefix) {
+                    if (!isset($this->parentPrefixes[$locale])) {
+                        throw new \LogicException(sprintf('Collection "%s" with locale "%s" is missing a corresponding prefix in its parent collection.', $this->name, $locale));
+                    }
+
+                    $prefix[$locale] = $this->parentPrefixes[$locale].$localePrefix;
+                }
+            }
+            $this->prefixes = $prefix;
+            $this->route->setPath('/');
+        } else {
+            $this->prefixes = null;
+            $this->route->setPath($prefix);
+        }
 
         return $this;
     }
+
+    private function createRoute($path): Route
+    {
+        return (clone $this->route)->setPath($path);
+    }
 }

Loader/Configurator/ImportConfigurator.php

@@ -36,11 +36,36 @@ public function __destruct()
     /**
      * Sets the prefix to add to the path of all child routes.
      *
+     * @param string|array $prefix the prefix, or the localized prefixes
+     *
      * @return $this
      */
-    final public function prefix(string $prefix)
+    final public function prefix($prefix)
     {
-        $this->route->addPrefix($prefix);
+        if (!\is_array($prefix)) {
+            $this->route->addPrefix($prefix);
+        } else {
+            foreach ($prefix as $locale => $localePrefix) {
+                $prefix[$locale] = trim(trim($localePrefix), '/');
+            }
+            foreach ($this->route->all() as $name => $route) {
+                if (null === $locale = $route->getDefault('_locale')) {
+                    $this->route->remove($name);
+                    foreach ($prefix as $locale => $localePrefix) {
+                        $localizedRoute = clone $route;
+                        $localizedRoute->setDefault('_locale', $locale);
+                        $localizedRoute->setDefault('_canonical_route', $name);
+                        $localizedRoute->setPath($localePrefix.$route->getPath());
+                        $this->route->add($name.'.'.$locale, $localizedRoute);
+                    }
+                } elseif (!isset($prefix[$locale])) {
+                    throw new \InvalidArgumentException(sprintf('Route "%s" with locale "%s" is missing a corresponding prefix in its parent collection.', $name, $locale));
+                } else {
+                    $route->setPath($prefix[$locale].$route->getPath());
+                    $this->route->add($name, $route);
+                }
+            }
+        }
 
         return $this;
     }

Loader/Configurator/RouteConfigurator.php

@@ -11,7 +11,6 @@
 
 namespace Symfony\Component\Routing\Loader\Configurator;
 
-use Symfony\Component\Routing\Route;
 use Symfony\Component\Routing\RouteCollection;
 
 /**
@@ -24,11 +23,12 @@ class RouteConfigurator
 
     private $parentConfigurator;
 
-    public function __construct(RouteCollection $collection, Route $route, string $name = '', CollectionConfigurator $parentConfigurator = null)
+    public function __construct(RouteCollection $collection, $route, string $name = '', CollectionConfigurator $parentConfigurator = null, array $prefixes = null)
     {
         $this->collection = $collection;
         $this->route = $route;
         $this->name = $name;
         $this->parentConfigurator = $parentConfigurator; // for GC control
+        $this->prefixes = $prefixes;
     }
 }