[TASK] Establish proper API to set template layout (#1090)

The `ParsingState` now provides a proper method to set the
layout of a template during parsing/compilation. Previously, the
magic variable name `layoutName` has been used for that
purpose, but with the new `nodeInitializedEvent` we can now
access the `ParsingState` object directly.

The usage of the old variable name has been deprecated and
will no longer be evaluated with Fluid v5. Its main usage besides
the `<f:layout>` ViewHelper (see above) has been the cache
warmup command, which will receive a more straightforward
implementation with Fluid v5.

Author: s2b

Documentation/Changelog/4.x.rst

@@ -6,6 +6,14 @@
 Changelog 4.x
 =============
 
+4.4
+---
+
+* Deprecation: Setting a template's layout with the variable `layoutName` is deprecated and will no longer work in Fluid v5.
+  Use :php:`TYPO3Fluid\Fluid\Core\Parser\ParsingState->setLayoutName()` instead.
+* Deprecation: Constant :php:`TYPO3Fluid\Fluid\Core\Compiler\TemplateCompiler::LAYOUT_VARIABLE`
+  has been marked as deprecated and will be removed in Fluid v5.
+
 4.3
 ---
 

Documentation/Integrating/Index.rst

@@ -35,10 +35,11 @@ composition: which implementations of `TemplatePaths` the View requires, if it
 needs a :ref:`custom ViewHelperResolver <viewhelperresolver>`,
 if it must have some default variables, if it should have a default cache, etc.
 
-..  note::
-
-    The special variable `layoutName` is reserved and can be assigned to a
-    template to set its Layout instead of using `<f:layout name="LayoutName" />`.
+..  deprecated:: 4.4
+    Prevously, it was possible to set the layout of a template with the special
+    variable `layoutName`. This will no longer work with Fluid 5. Please use the
+    `<f:layout> ViewHelper <https://docs.typo3.org/permalink/fluid:typo3fluid-fluid-layout>`_
+    instead.
 
 .. _templatepaths:
 

Documentation/ViewHelpers/Fluid.json

@@ -12,5 +12,10 @@
 Flatten ViewHelper `<f:flatten>`
 ================================
 
+.. ..  note::
+..     This reference is part of the documentation of Fluid Standalone.
+..     If you are working with Fluid in TYPO3 CMS, please refer to
+..     :doc:`TYPO3's ViewHelper reference <t3viewhelper:Global/Flatten>` instead.
+
 ..  typo3:viewhelper:: flatten
     :source: ../Fluid.json

Documentation/ViewHelpers/Fluid/Flatten.rst

@@ -12,5 +12,10 @@
 Shuffle ViewHelper `<f:shuffle>`
 ================================
 
+.. ..  note::
+..     This reference is part of the documentation of Fluid Standalone.
+..     If you are working with Fluid in TYPO3 CMS, please refer to
+..     :doc:`TYPO3's ViewHelper reference <t3viewhelper:Global/Shuffle>` instead.
+
 ..  typo3:viewhelper:: shuffle
     :source: ../Fluid.json

Documentation/ViewHelpers/Fluid/Shuffle.rst

@@ -12,7 +12,6 @@
 use TYPO3Fluid\Fluid\Core\Parser\ParsedTemplateInterface;
 use TYPO3Fluid\Fluid\Core\Parser\ParsingState;
 use TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\NodeInterface;
-use TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\RootNode;
 use TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\ViewHelperNode;
 use TYPO3Fluid\Fluid\Core\Rendering\RenderingContextInterface;
 use TYPO3Fluid\Fluid\Core\ViewHelper\ArgumentDefinition;
@@ -37,8 +36,7 @@ class TemplateCompiler
      * Variable name to be used to transfer information about a template's layout
      * from the ViewHelper context to the TemplateView and the TemplateCompiler
      *
-     * @todo This data-shuffling between parser, compiler and renderer should be
-     *       avoided in the future.
+     * @deprecated variable will no longer be necessary in Fluid v5
      */
     public const LAYOUT_VARIABLE = 'layoutName';
 
@@ -174,7 +172,7 @@ public function store(string $identifier, ParsingState $parsingState): ?string
             'Main Render function',
         );
 
-        $storedLayoutName = $parsingState->getVariableContainer()->get(static::LAYOUT_VARIABLE);
+        $storedLayoutName = $parsingState->getUnevaluatedLayoutName();
         $templateCode = sprintf(
             '<?php' . chr(10) .
             '%s {' . chr(10) .
@@ -203,12 +201,9 @@ public function store(string $identifier, ParsingState $parsingState): ?string
         return $templateCode;
     }
 
-    /**
-     * @todo this type is crazy, this should really be something like NodeInterface|string
-     */
-    protected function generateCodeForLayoutName(NodeInterface|string|int|float|null|bool $storedLayoutNameArgument): string
+    protected function generateCodeForLayoutName(NodeInterface|string|null $storedLayoutNameArgument): string
     {
-        if ($storedLayoutNameArgument instanceof RootNode) {
+        if ($storedLayoutNameArgument instanceof NodeInterface) {
             $convertedCode = $storedLayoutNameArgument->convert($this);
             $initialization = $convertedCode['initialization'];
             $execution = $convertedCode['execution'];

src/Core/Compiler/TemplateCompiler.php

@@ -52,6 +52,8 @@ public function getVariableContainer(): VariableProviderInterface;
      * Returns the name of the layout that is defined within the current template via <f:layout name="..." />
      * If no layout is defined, this returns null.
      * This requires the current rendering context in order to be able to evaluate the layout name
+     *
+     * @todo remove NodeInterface from return types in Fluid v5
      */
     public function getLayoutName(RenderingContextInterface $renderingContext): string|null|NodeInterface;
 

src/Core/Parser/ParsedTemplateInterface.php

@@ -27,6 +27,7 @@
 class ParsingState implements ParsedTemplateInterface
 {
     protected string $identifier;
+    protected string|NodeInterface|null $layoutName = null;
 
     /**
      * @var array<string, ArgumentDefinition>
@@ -205,7 +206,8 @@ public function getVariableContainer(): VariableProviderInterface
      */
     public function hasLayout(): bool
     {
-        return $this->variableContainer->exists(TemplateCompiler::LAYOUT_VARIABLE);
+        // @todo remove fallback with Fluid v5
+        return isset($this->layoutName) || $this->variableContainer->exists(TemplateCompiler::LAYOUT_VARIABLE);
     }
 
     /**
@@ -215,10 +217,29 @@ public function hasLayout(): bool
      *
      * @throws View\Exception
      */
-    public function getLayoutName(RenderingContextInterface $renderingContext): string|null|NodeInterface
+    public function getLayoutName(RenderingContextInterface $renderingContext): ?string
     {
-        $layoutName = $this->variableContainer->get(TemplateCompiler::LAYOUT_VARIABLE);
-        return $layoutName instanceof RootNode ? $layoutName->evaluate($renderingContext) : $layoutName;
+        $layoutName = $this->getUnevaluatedLayoutName();
+        return $layoutName instanceof NodeInterface ? $layoutName->evaluate($renderingContext) : $layoutName;
+    }
+
+    /**
+     * @internal only to be used by TemplateCompiler
+     */
+    public function getUnevaluatedLayoutName(): NodeInterface|string|null
+    {
+        // @todo remove fallback with Fluid v5
+        if (!isset($this->layoutName) && $this->variableContainer->exists(TemplateCompiler::LAYOUT_VARIABLE)) {
+            trigger_error('Setting a template\'s layout with the variable "layoutName" is deprecated and will no longer work in Fluid v5. Use ParsingState->setLayoutName() instead.', E_USER_DEPRECATED);
+            $layoutName = $this->variableContainer->get(TemplateCompiler::LAYOUT_VARIABLE);
+            return !$layoutName instanceof NodeInterface && !is_null($layoutName) ? (string)$layoutName : $layoutName;
+        }
+        return $this->layoutName;
+    }
+
+    public function setLayoutName(string|NodeInterface|null $layoutName): void
+    {
+        $this->layoutName = $layoutName;
     }
 
     public function addCompiledNamespaces(RenderingContextInterface $renderingContext): void {}

src/Core/Parser/ParsingState.php

@@ -15,7 +15,11 @@
 use TYPO3Fluid\Fluid\Core\ViewHelper\ViewHelperNodeInitializedEventInterface;
 
 /**
- * With this tag, you can select a layout to be used for the current template.
+ * With this ViewHelper, you can select a layout to be used for the current template.
+ *
+ * ..  deprecated:: 4.4
+ *     Prevously, it was possible to set the layout of a template with the special
+ *     variable `layoutName`. This will no longer work with Fluid 5.
  *
  * Examples
  * ========
@@ -62,8 +66,8 @@ final public function convert(TemplateCompiler $templateCompiler): array
     }
 
     /**
-     * On the node initialized event, add the "layoutName" variable to the variable container so it can
-     * be used by the TemplateView.
+     * Set the defined layout name (which can include variables) to the ParsingState,
+     * to be used both for compilation and uncached rendering
      *
      * @param array<string, NodeInterface> $arguments Unevaluated ViewHelper arguments
      */
@@ -74,6 +78,6 @@ public static function nodeInitializedEvent(ViewHelperNode $node, array $argumen
         } else {
             $layoutNameNode = 'Default';
         }
-        $parsingState->getVariableContainer()->add(TemplateCompiler::LAYOUT_VARIABLE, $layoutNameNode);
+        $parsingState->setLayoutName($layoutNameNode);
     }
 }

src/ViewHelpers/LayoutViewHelper.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file belongs to the package "TYPO3 Fluid".
+ * See LICENSE.txt that was shipped with this package.
+ */
+
+namespace TYPO3Fluid\Fluid\Tests\Functional\Core\Rendering;
+
+use PHPUnit\Framework\Attributes\IgnoreDeprecations;
+use PHPUnit\Framework\Attributes\Test;
+use TYPO3Fluid\Fluid\Tests\Functional\AbstractFunctionalTestCase;
+use TYPO3Fluid\Fluid\View\TemplateView;
+
+final class LayoutNameVariableTest extends AbstractFunctionalTestCase
+{
+    #[Test]
+    #[IgnoreDeprecations]
+    public function layoutVariable(): void
+    {
+        $view = new TemplateView();
+        $view->getRenderingContext()->setCache(self::$cache);
+        $view->getRenderingContext()->getVariableProvider()->add('layoutName', 'Default');
+        $view->getRenderingContext()->getTemplatePaths()->setLayoutRootPaths([__DIR__ . '/../../Fixtures/Layouts/']);
+        $view->getRenderingContext()->getTemplatePaths()->setTemplateSource('');
+        self::assertSame('DefaultLayout with name Default.html', trim($view->render()), 'uncached');
+
+        $view = new TemplateView();
+        $view->getRenderingContext()->setCache(self::$cache);
+        $view->getRenderingContext()->getVariableProvider()->add('layoutName', 'Default');
+        $view->getRenderingContext()->getTemplatePaths()->setLayoutRootPaths([__DIR__ . '/../../Fixtures/Layouts/']);
+        $view->getRenderingContext()->getTemplatePaths()->setTemplateSource('');
+        self::assertSame('DefaultLayout with name Default.html', trim($view->render()), 'cached');
+    }
+}