EZP-24765: Give possibility to set additional paths for a given theme

> https://jira.ez.no/browse/EZP-27465

This patch makes it possible to add arbitrary Twig template directories to a theme from configuration.
This can be useful when you want to define templates from third-party bundles as part of one of your themes,
or when upgrading your application in order to use eZ Platform design engine, and that your existing templates
are not yet following the convention.

Practical use case would be to define a `standard` theme for templates provided by the kernel.

```yaml
ezdesign:
    design_list:
        my_design: [my_theme, some_other_theme]
    templates_theme_paths:
        # FOSUserBundle templates will be part of "my_theme" theme
        my_theme:
            - '%kernel.root_dir%/../vendor/friendsofsymfony/user-bundle/Resources/views'
```

bundle/DependencyInjection/Compiler/TwigThemePass.php

@@ -69,6 +69,10 @@ public function process(ContainerBuilder $container)
             }
         }
 
+        // Now merge with already configured template theme paths
+        // Template theme paths defined via config will always have less priority than convention based paths
+        $themesPathMap = array_merge_recursive($themesPathMap, $container->getParameter('ezdesign.templates_path_map'));
+
         // De-duplicate the map
         foreach ($themesPathMap as $theme => &$paths) {
             $paths = array_unique($paths);

bundle/DependencyInjection/Configuration.php

@@ -29,7 +29,16 @@ public function getConfigTreeBuilder()
                         ->prototype('scalar')->end()
                     ->end()
                 ->end()
-                ->arrayNode('template_override_paths')
+                ->arrayNode('templates_theme_paths')
+                    ->useAttributeAsKey('theme')
+                    ->example(['some_theme' => ['/var/foo/some_theme_dir', '/another/theme/dir']])
+                    ->info('Collection of template paths by theme.')
+                    ->prototype('array')
+                        ->info('Each path MUST exist')
+                        ->prototype('scalar')->end()
+                    ->end()
+                ->end()
+                ->arrayNode('templates_override_paths')
                     ->info('Directories to add to the override list for templates. Those directories will be checked before theme directories.')
                     ->prototype('scalar')->end()
                 ->end()

bundle/DependencyInjection/EzPlatformDesignEngineExtension.php

@@ -45,7 +45,8 @@ private function configureDesigns(array $config, ConfigurationProcessor $process
         // Always add "standard" design to the list (defaults to application level & override paths only)
         $config['design_list'] += ['standard' => []];
         $container->setParameter('ezdesign.design_list', $config['design_list']);
-        $container->setParameter('ezdesign.templates_override_paths', $config['template_override_paths']);
+        $container->setParameter('ezdesign.templates_override_paths', $config['templates_override_paths']);
+        $container->setParameter('ezdesign.templates_path_map', $config['templates_theme_paths']);
         $container->setParameter('ezdesign.asset_resolution.disabled', $config['disable_assets_pre_resolution']);
 
         // PHPStorm settings

doc/templates.md

@@ -41,12 +41,31 @@ Default fallback order is the following:
 
 > Bundle fallback order is the instantiation order in `AppKernel`.
 
+### Additional theme paths
+In addition to the convention described above, it is also possible to add arbitrary Twig template directories to a theme
+from configuration. This can be useful when you want to define templates from third-party bundles as part of one of your
+themes, or when upgrading your application in order to use eZ Platform design engine, and that your existing templates
+are not yet following the convention.
+
+```yaml
+ezdesign:
+    design_list:
+        my_design: [my_theme, some_other_theme]
+    templates_theme_paths:
+        # FOSUserBundle templates will be part of "my_theme" theme
+        my_theme:
+            - '%kernel.root_dir%/../vendor/friendsofsymfony/user-bundle/Resources/views'
+```
+
+> **Paths precedence**: Directories following the convention will **always** have the precedence over the ones defined
+> in config. This ensures that it is always possible to override a template from the application.
+
 ### Additional override paths
 It is possible to add addition global override directories, similar to `app/Resources/views/`.
 
 ```yaml
 ezdesign:
-    template_override_paths:
+    templates_override_paths:
         - "%kernel.root_dir%/another_override_directory"
         - "/some/other/directory"
 ```