feature #43108 [HttpKernel] Add basic support for language negotiation (GregoireHebert)

This PR was merged into the 5.4 branch.

Discussion
----------

[HttpKernel] Add basic support for language negotiation

| Q             | A
| ------------- | ---
| Branch?       | 5.4
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       | -
| License       | MIT
| Doc PR        | -

Continuation of #36507. Thanks `@GregoireHebert`!

This PR adds two options to the framework configuration:
- `set_locale_from_accept_language`: Makes the `Request`' locale automatically set based on the `Accept-Language` header (restricted by a new `framework.enabled_locales` config option which replaces `framework.translator.enabled_locales`).
The explicit `_locale` request attribute always wins over the `Accept-Language` header when it's set.
- `set_content_language_from_locale`: Sets the `Content-Language` Response header based on the `Request`' locale.

This is going to be useful for API Platform and related (e.g. Sylius/Sylius#11412).

Commits
-------

904b54f1f8 [HttpKernel] Add basic support for language negotiation

Author: derrabus

CHANGELOG.md

@@ -4,6 +4,10 @@ CHANGELOG
 5.4
 ---
 
+ * Add `set_locale_from_accept_language` config option to automatically set the request locale based on the `Accept-Language`
+   HTTP request header and the `framework.enabled_locales` config option
+ * Add `set_content_language_from_locale` config option to automatically set the `Content-Language` HTTP response header based on the Request locale
+ * Deprecate the `framework.translator.enabled_locales`, use `framework.enabled_locales` instead
  * Add autowiring alias for `HttpCache\StoreInterface`
  * Deprecate the `AdapterInterface` autowiring alias, use `CacheItemPoolInterface` instead
  * Deprecate the public `profiler` service to private

DependencyInjection/Configuration.php

@@ -77,6 +77,7 @@ public function getConfigTreeBuilder()
                     return $v;
                 })
             ->end()
+            ->fixXmlConfig('enabled_locale')
             ->children()
                 ->scalarNode('secret')->end()
                 ->scalarNode('http_method_override')
@@ -86,6 +87,18 @@ public function getConfigTreeBuilder()
                 ->scalarNode('ide')->defaultNull()->end()
                 ->booleanNode('test')->end()
                 ->scalarNode('default_locale')->defaultValue('en')->end()
+                ->booleanNode('set_locale_from_accept_language')
+                    ->info('Whether to use the Accept-Language HTTP header to set the Request locale (only when the "_locale" request attribute is not passed).')
+                    ->defaultFalse()
+                ->end()
+                ->booleanNode('set_content_language_from_locale')
+                    ->info('Whether to set the Content-Language HTTP header on the Response using the Request locale.')
+                    ->defaultFalse()
+                ->end()
+                ->arrayNode('enabled_locales')
+                    ->info('Defines the possible locales for the application. This list is used for generating translations files, but also to restrict which locales are allowed when it is set from Accept-Language header (using "set_locale_from_accept_language").')
+                    ->prototype('scalar')->end()
+                ->end()
                 ->arrayNode('trusted_hosts')
                     ->beforeNormalization()->ifString()->then(function ($v) { return [$v]; })->end()
                     ->prototype('scalar')->end()
@@ -814,6 +827,7 @@ private function addTranslatorSection(ArrayNodeDefinition $rootNode, callable $e
                             ->prototype('scalar')->end()
                         ->end()
                         ->arrayNode('enabled_locales')
+                            ->setDeprecated('symfony/framework-bundle', '5.3', 'Option "%node%" at "%path%" is deprecated, set the "framework.enabled_locales" option instead.')
                             ->prototype('scalar')->end()
                             ->defaultValue([])
                         ->end()
@@ -848,7 +862,7 @@ private function addTranslatorSection(ArrayNodeDefinition $rootNode, callable $e
                                     ->arrayNode('locales')
                                         ->prototype('scalar')->end()
                                         ->defaultValue([])
-                                        ->info('If not set, all locales listed under framework.translator.enabled_locales are used.')
+                                        ->info('If not set, all locales listed under framework.enabled_locales are used.')
                                     ->end()
                                 ->end()
                             ->end()

DependencyInjection/FrameworkExtension.php

@@ -275,6 +275,9 @@ public function load(array $configs, ContainerBuilder $container)
             }
         }
 
+        $container->getDefinition('locale_listener')->replaceArgument(3, $config['set_locale_from_accept_language']);
+        $container->getDefinition('response_listener')->replaceArgument(1, $config['set_content_language_from_locale']);
+
         // If the slugger is used but the String component is not available, we should throw an error
         if (!ContainerBuilder::willBeAvailable('symfony/string', SluggerInterface::class, ['symfony/framework-bundle'])) {
             $container->register('slugger', 'stdClass')
@@ -297,6 +300,7 @@ public function load(array $configs, ContainerBuilder $container)
         $container->setParameter('kernel.http_method_override', $config['http_method_override']);
         $container->setParameter('kernel.trusted_hosts', $config['trusted_hosts']);
         $container->setParameter('kernel.default_locale', $config['default_locale']);
+        $container->setParameter('kernel.enabled_locales', $config['enabled_locales']);
         $container->setParameter('kernel.error_controller', $config['error_controller']);
 
         if (($config['trusted_proxies'] ?? false) && ($config['trusted_headers'] ?? false)) {
@@ -418,11 +422,13 @@ public function load(array $configs, ContainerBuilder $container)
         $this->registerEsiConfiguration($config['esi'], $container, $loader);
         $this->registerSsiConfiguration($config['ssi'], $container, $loader);
         $this->registerFragmentsConfiguration($config['fragments'], $container, $loader);
-        $this->registerTranslatorConfiguration($config['translator'], $container, $loader, $config['default_locale']);
+        $this->registerTranslatorConfiguration($config['translator'], $container, $loader, $config['default_locale'], $config['enabled_locales']);
         $this->registerProfilerConfiguration($config['profiler'], $container, $loader);
         $this->registerWorkflowConfiguration($config['workflows'], $container, $loader);
         $this->registerDebugConfiguration($config['php_errors'], $container, $loader);
-        $this->registerRouterConfiguration($config['router'], $container, $loader, $config['translator']['enabled_locales'] ?? []);
+        // @deprecated since Symfony 5.4, in 6.0 change to:
+        // $this->registerRouterConfiguration($config['router'], $container, $loader, $config['enabled_locales']);
+        $this->registerRouterConfiguration($config['router'], $container, $loader, $config['translator']['enabled_locales'] ?: $config['enabled_locales']);
         $this->registerAnnotationsConfiguration($config['annotations'], $container, $loader);
         $this->registerPropertyAccessConfiguration($config['property_access'], $container, $loader);
         $this->registerSecretsConfiguration($config['secrets'], $container, $loader);
@@ -1228,7 +1234,7 @@ private function createVersion(ContainerBuilder $container, ?string $version, ?s
         return new Reference('assets.empty_version_strategy');
     }
 
-    private function registerTranslatorConfiguration(array $config, ContainerBuilder $container, LoaderInterface $loader, string $defaultLocale)
+    private function registerTranslatorConfiguration(array $config, ContainerBuilder $container, LoaderInterface $loader, string $defaultLocale, array $enabledLocales)
     {
         if (!$this->isConfigEnabled($container, $config)) {
             $container->removeDefinition('console.command.translation_debug');
@@ -1252,7 +1258,9 @@ private function registerTranslatorConfiguration(array $config, ContainerBuilder
         $defaultOptions['cache_dir'] = $config['cache_dir'];
         $translator->setArgument(4, $defaultOptions);
 
-        $translator->setArgument(5, $config['enabled_locales']);
+        // @deprecated since Symfony 5.4, in 6.0 change to:
+        // $translator->setArgument(5, $enabledLocales);
+        $translator->setArgument(5, $config['enabled_locales'] ?: $enabledLocales);
 
         $container->setParameter('translator.logging', $config['logging']);
         $container->setParameter('translator.default_path', $config['default_path']);
@@ -1385,7 +1393,9 @@ private function registerTranslatorConfiguration(array $config, ContainerBuilder
             return;
         }
 
-        $locales = $config['enabled_locales'] ?? [];
+        // @deprecated since Symfony 5.4, in 6.0 change to:
+        // $locales = $enabledLocales;
+        $locales = $config['enabled_locales'] ?: $enabledLocales;
 
         foreach ($config['providers'] as $provider) {
             if ($provider['locales']) {

Resources/config/schema/symfony-1.0.xsd

@@ -38,12 +38,15 @@
             <xsd:element name="rate-limiter" type="rate_limiter" minOccurs="0" maxOccurs="1" />
             <xsd:element name="uid" type="uid" minOccurs="0" maxOccurs="1" />
             <xsd:element name="notifier" type="notifier" minOccurs="0" maxOccurs="1" />
+            <xsd:element name="enabled-locale" type="xsd:string" minOccurs="0" maxOccurs="unbounded" />
         </xsd:choice>
 
         <xsd:attribute name="http-method-override" type="xsd:boolean" />
         <xsd:attribute name="ide" type="xsd:string" />
         <xsd:attribute name="secret" type="xsd:string" />
         <xsd:attribute name="default-locale" type="xsd:string" />
+        <xsd:attribute name="set_locale_from_accept_language" type="xsd:boolean" />
+        <xsd:attribute name="set_content_language_from_locale" type="xsd:boolean" />
         <xsd:attribute name="test" type="xsd:boolean" />
         <xsd:attribute name="error-controller" type="xsd:string" />
         <xsd:attribute name="trusted-hosts" type="xsd:string" />

Resources/config/web.php

@@ -69,6 +69,8 @@
         ->set('response_listener', ResponseListener::class)
             ->args([
                 param('kernel.charset'),
+                abstract_arg('The "set_content_language_from_locale" config value'),
+                param('kernel.enabled_locales'),
             ])
             ->tag('kernel.event_subscriber')
 
@@ -80,6 +82,8 @@
                 service('request_stack'),
                 param('kernel.default_locale'),
                 service('router')->ignoreOnInvalid(),
+                abstract_arg('The "set_locale_from_accept_language" config value'),
+                param('kernel.enabled_locales'),
             ])
             ->tag('kernel.event_subscriber')
 

Tests/DependencyInjection/ConfigurationTest.php

@@ -370,6 +370,9 @@ protected static function getBundleDefaultConfig()
             'http_method_override' => true,
             'ide' => null,
             'default_locale' => 'en',
+            'enabled_locales' => [],
+            'set_locale_from_accept_language' => false,
+            'set_content_language_from_locale' => false,
             'secret' => 's3cr3t',
             'trusted_hosts' => [],
             'trusted_headers' => [

Tests/DependencyInjection/Fixtures/php/full.php

@@ -3,6 +3,7 @@
 $container->loadFromExtension('framework', [
     'secret' => 's3cr3t',
     'default_locale' => 'fr',
+    'enabled_locales' => ['fr', 'en'],
     'csrf_protection' => true,
     'form' => [
         'csrf_protection' => [
@@ -51,7 +52,6 @@
         'fallback' => 'fr',
         'paths' => ['%kernel.project_dir%/Fixtures/translations'],
         'cache_dir' => '%kernel.cache_dir%/translations',
-        'enabled_locales' => ['fr', 'en'],
     ],
     'validation' => [
         'enabled' => true,

Tests/DependencyInjection/Fixtures/php/legacy_translator_enabled_locales.php

@@ -0,0 +1,18 @@
+<?php
+
+$container->loadFromExtension('framework', [
+    'secret' => 's3cr3t',
+    'default_locale' => 'fr',
+    'router' => [
+        'resource' => '%kernel.project_dir%/config/routing.xml',
+        'type' => 'xml',
+        'utf8' => true,
+    ],
+    'translator' => [
+        'enabled' => true,
+        'fallback' => 'fr',
+        'paths' => ['%kernel.project_dir%/Fixtures/translations'],
+        'cache_dir' => '%kernel.cache_dir%/translations',
+        'enabled_locales' => ['fr', 'en'],
+    ],
+]);

Tests/DependencyInjection/Fixtures/xml/full.xml

@@ -7,6 +7,8 @@
                         http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
     <framework:config secret="s3cr3t" ide="file%%link%%format" default-locale="fr" http-method-override="false">
+        <framework:enabled-locale>fr</framework:enabled-locale>
+        <framework:enabled-locale>en</framework:enabled-locale>
         <framework:csrf-protection />
         <framework:form legacy-error-messages="false">
             <framework:csrf-protection field-name="_csrf"/>
@@ -28,8 +30,6 @@
         <framework:assets version="v1" />
         <framework:translator enabled="true" fallback="fr" logging="true" cache-dir="%kernel.cache_dir%/translations">
             <framework:path>%kernel.project_dir%/Fixtures/translations</framework:path>
-            <framework:enabled-locale>fr</framework:enabled-locale>
-            <framework:enabled-locale>en</framework:enabled-locale>
         </framework:translator>
         <framework:validation enabled="true" />
         <framework:annotations cache="file" debug="true" file-cache-dir="%kernel.cache_dir%/annotations" />

Tests/DependencyInjection/Fixtures/xml/legacy_translator_enabled_locales.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" ?>
+
+<container xmlns="http://symfony.com/schema/dic/services"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns:framework="http://symfony.com/schema/dic/symfony"
+    xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
+                        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+    <framework:config secret="s3cr3t" ide="file%%link%%format" default-locale="fr" http-method-override="false">
+        <framework:router resource="%kernel.project_dir%/config/routing.xml" type="xml" utf8="true" />
+        <framework:translator enabled="true" fallback="fr" logging="true" cache-dir="%kernel.cache_dir%/translations">
+            <framework:path>%kernel.project_dir%/Fixtures/translations</framework:path>
+            <framework:enabled-locale>fr</framework:enabled-locale>
+            <framework:enabled-locale>en</framework:enabled-locale>
+        </framework:translator>
+    </framework:config>
+</container>