[FEATURE] Introduce optional .fluid.* file extension (#1258)

Historically, Fluid has always used generic file extensions for
template files, such as `.html`, `.txt` or `.xml`. While this
provides IDE integration out-of-the-box, it makes it hard to
distinguish files that are interpreted by Fluid and others that
are just text or html files.

This patch introduces an optional (!) new file extension for
Fluid template files that is added _in addition_ to the generic
file extension: `.fluid.html` for html files, `.fluid.txt` for
text files, and so on. Template files are now detected in the
following order (first existing file wins):

```
templateRootPath: templates/
template: myTemplate
format: html

1. templates/myTemplate.fluid.html
2. templates/myTemplate.html
3. templates/myTemplate
4. templates/MyTemplate.fluid.html
5. templates/MyTemplate.html
6. templates/MyTemplate
```

If multiple template paths are defined, this chain is executed for
each path separately, before falling back to the next path. This
means that (in the TYPO3 context) an extension can ship `.html`
files and another extension can override these files with `.fluid.html`
files. It also works in reverse: The extension can ship `.fluid.html`,
which can be overwritten with `.html` files. In short: The order
of paths is respected, regardless of the file extension. This will
make it possible to ship TYPO3 extensions compatible with v13/v14
(= ships `.html`), while a sitepackage in a v14 project can already
use `.fluid.html` files. It also means that the core can rename all
templates to `.fluid.html` without breaking extensions that overwrite
core templates (e. g. email templates) with `.html` files.

The order of file extensions has been discussed intensively, but in
the end we decided to land on `.fluid.*`. Major reasons:

* We currently already have mediocre IDE/editor support at best.
  Using `.fluid` as primary file extension would remove code
  highlighting completely until we can address each highlighter
  individually. This would also include things like Gerrit, GitHub
  or GitLab. Our time is not well spent to introduce a completely
  new file extension when there's an easier alternative.
* With `*.form.yaml` there is already precedent in the TYPO3 cosmos.

Introducing this file extension not only helps users to
recognize Fluid templates, it also allows us to create better IDE
integrations in the future. Also, it enables us to scan a whole project
for Fluid templates, which makes cache warmup and linting tasks
config-free.

Author: s2b

src/View/TemplatePaths.php

@@ -41,6 +41,7 @@
  */
 class TemplatePaths
 {
+    public const FLUID_EXTENSION = 'fluid';
     public const DEFAULT_FORMAT = 'html';
     public const CONFIG_TEMPLATEROOTPATHS = 'templateRootPaths';
     public const CONFIG_LAYOUTROOTPATHS = 'layoutRootPaths';
@@ -544,13 +545,16 @@ protected function resolveFileInPaths(array $paths, string $fileName, string $fo
     {
         // Create array of possible template paths. This includes:
         // * with and without format as file extension
+        // * with and without *.fluid.* file extension
         // * fallback to uppercase file name
         $possibleTemplates = [];
         foreach (array_reverse($paths) as $path) {
+            $possibleTemplates[] = $path . $fileName . '.' . static::FLUID_EXTENSION . '.' . $format;
             $possibleTemplates[] = $path . $fileName . '.' . $format;
             $possibleTemplates[] = $path . $fileName;
             $uppercaseName = ucfirst($fileName);
             if ($uppercaseName !== $fileName) {
+                $possibleTemplates[] = $path . $uppercaseName . '.' . static::FLUID_EXTENSION . '.' . $format;
                 $possibleTemplates[] = $path . $uppercaseName . '.' . $format;
                 $possibleTemplates[] = $path . $uppercaseName;
             }

tests/Unit/View/Fixtures/TemplateResolving/Templates1/FluidExtensionOverrideTest.fluid.html

@@ -265,6 +265,38 @@ public static function resolveTemplateFileForControllerAndActionAndFormatDataPro
                 'OnlyInFirst',
                 __DIR__ . '/Fixtures/TemplateResolving/Templates1/OnlyInFirst.html',
             ],
+            'fluid extension is used' => [
+                [__DIR__ . '/Fixtures/TemplateResolving/Templates1'],
+                '',
+                'FluidExtensionTest',
+                __DIR__ . '/Fixtures/TemplateResolving/Templates1/FluidExtensionTest.fluid.html',
+            ],
+            'non-fluid extension can be used with full name' => [
+                [__DIR__ . '/Fixtures/TemplateResolving/Templates1'],
+                '',
+                'FluidExtensionOverrideTest.html',
+                __DIR__ . '/Fixtures/TemplateResolving/Templates1/FluidExtensionOverrideTest.html',
+            ],
+            'fluid extension is preferred if both exist within one path' => [
+                [__DIR__ . '/Fixtures/TemplateResolving/Templates1'],
+                '',
+                'FluidExtensionOverrideTest',
+                __DIR__ . '/Fixtures/TemplateResolving/Templates1/FluidExtensionOverrideTest.fluid.html',
+            ],
+            // Use case: TYPO3 extension ships .html files, TYPO3 sitepackage overrides with .fluid.html
+            'fluid extension overrides non-fluid extension from previous paths' => [
+                [__DIR__ . '/Fixtures/TemplateResolving/Templates1', __DIR__ . '/Fixtures/TemplateResolving/Templates2'],
+                '',
+                'OriginalWithoutFluidExtension',
+                __DIR__ . '/Fixtures/TemplateResolving/Templates2/OriginalWithoutFluidExtension.fluid.html',
+            ],
+            // Use case: TYPO3 core ships .fluid.html, TYPO3 extension overrides with .html
+            'non-fluid extension overrides fluid extension from previous paths' => [
+                [__DIR__ . '/Fixtures/TemplateResolving/Templates1', __DIR__ . '/Fixtures/TemplateResolving/Templates2'],
+                '',
+                'OriginalWithFluidExtension',
+                __DIR__ . '/Fixtures/TemplateResolving/Templates2/OriginalWithFluidExtension.html',
+            ],
         ];
     }