[FEATURE] Introduce argument definitions for templates and partials

The new `<f:argument>` ViewHelper allows to define an API
for templates, partials and layouts that will be validated when
the template/partial/layout is rendered. For each argument,
a type can be defined. By default, arguments are defined as
non-optional, but they can be defined as optional by using
`optional="{false}"`. Optional arguments can have default
values, which are defined with `default="my default value"`.

To avoid unnecessary complexity, the ViewHelper ensures that
no dynamic content (like variables) can be used in an argument
definition. Also, `<f:argument>` can't be nested into other
ViewHelpers.

Template argument definitions are processed and verified
by the new `StrictArgumentProcessor`, which properly
ensures argument types by casting scalar values and checking
the types more thoroughly than the `LenientArgumentProcessor`.
This means that currently template arguments are validated
in a different way than ViewHelper arguments, however
this will be resolved with Fluid v5.

Currently, there is no way to prohibit additional arguments
that are not defined with the `<f:argument>` ViewHelper,
however this might still be added in the future.

Author: s2b

Documentation/ViewHelpers/Fluid.json

@@ -0,0 +1,21 @@
+..  This reStructured text file has been automatically generated, do not change.
+..  Source: https://github.com/TYPO3/Fluid/blob/main/src/ViewHelpers/ArgumentViewHelper.php
+
+:edit-on-github-link: https://github.com/TYPO3/Fluid/edit/main/src/ViewHelpers/ArgumentViewHelper.php
+:navigation-title: argument
+
+..  include:: /Includes.rst.txt
+
+..  _typo3fluid-fluid-argument:
+
+==================================
+Argument ViewHelper `<f:argument>`
+==================================
+
+.. ..  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/Argument>` instead.
+
+..  typo3:viewhelper:: argument
+    :source: ../Fluid.json

Documentation/ViewHelpers/Fluid/Argument.rst

@@ -0,0 +1,9 @@
+<f:argument name="title" type="string" />
+<f:argument name="tags" type="string[]" optional="{true}" />
+<f:argument name="user" type="string" optional="{true}" default="admin" />
+
+Title: {title}<br />
+<f:if condition="{tags}">
+  Tags: {tags -> f:join(separator: ', ')}<br />
+</f:if>
+User: {user}

examples/Resources/Private/Singles/TemplateArguments.html

@@ -0,0 +1,36 @@
+<?php
+
+/*
+ * This file belongs to the package "TYPO3 Fluid".
+ * See LICENSE.txt that was shipped with this package.
+ */
+
+/**
+ * EXAMPLE: Template arguments
+ *
+ * This example demonstrates the possibility to declare
+ * argument definitions for template files, which need
+ * to be met by the provided variables.
+ */
+
+use TYPO3Fluid\FluidExamples\Helper\ExampleHelper;
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+$exampleHelper = new ExampleHelper();
+$view = $exampleHelper->init();
+
+$view->assignMultiple([
+    'title' => 'My title',
+    'tags' => ['tag1', 'tag2'],
+]);
+
+// Assigning the template path and filename to be rendered. Doing this overrides
+// resolving normally done by the TemplatePaths and directly renders this file.
+$paths = $view->getRenderingContext()->getTemplatePaths();
+$paths->setTemplatePathAndFilename(__DIR__ . '/Resources/Private/Singles/TemplateArguments.html');
+
+// Rendering the View: plain old rendering of single file, no bells and whistles.
+$output = $view->render();
+
+$exampleHelper->output($output);

examples/example_templatearguments.php

@@ -34,6 +34,11 @@ public function getVariableContainer(): VariableProviderInterface
         return new StandardVariableProvider();
     }
 
+    public function getArgumentDefinitions(): array
+    {
+        return [];
+    }
+
     /**
      * Render the parsed template with rendering context
      *

src/Core/Compiler/AbstractCompiledTemplate.php

@@ -15,6 +15,7 @@
 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;
 
 /**
  * @internal Nobody should need to override this class.
@@ -178,11 +179,13 @@ public function store(string $identifier, ParsingState $parsingState): ?string
             '        $renderingContext->getViewHelperResolver()->addNamespaces(%s);' . chr(10) .
             '    }' . chr(10) .
             '    %s' . chr(10) .
+            '    %s' . chr(10) .
             '}' . chr(10),
             'class ' . $identifier . ' extends \TYPO3Fluid\Fluid\Core\Compiler\AbstractCompiledTemplate',
             $this->generateCodeForLayoutName($storedLayoutName),
             ($parsingState->hasLayout() ? 'true' : 'false'),
             var_export($this->renderingContext->getViewHelperResolver()->getNamespaces(), true),
+            $this->generateArgumentDefinitionsCodeFromParsingState($parsingState),
             $generatedRenderFunctions,
         );
         $this->renderingContext->getCache()->set($identifier, $templateCode);
@@ -222,6 +225,31 @@ protected function generateSectionCodeFromParsingState(ParsingState $parsingStat
         return $generatedRenderFunctions;
     }
 
+    protected function generateArgumentDefinitionsCodeFromParsingState(ParsingState $parsingState): string
+    {
+        $argumentDefinitions = $parsingState->getArgumentDefinitions();
+        if ($argumentDefinitions === []) {
+            return '';
+        }
+        $argumentDefinitionsCode = array_map(
+            static fn(ArgumentDefinition $argumentDefinition): string => sprintf(
+                'new \\TYPO3Fluid\\Fluid\\Core\\ViewHelper\\ArgumentDefinition(%s, %s, %s, %s, %s, %s)',
+                var_export($argumentDefinition->getName(), true),
+                var_export($argumentDefinition->getType(), true),
+                var_export($argumentDefinition->getDescription(), true),
+                var_export($argumentDefinition->isRequired(), true),
+                var_export($argumentDefinition->getDefaultValue(), true),
+                var_export($argumentDefinition->getEscape(), true),
+            ),
+            $argumentDefinitions,
+        );
+        return 'public function getArgumentDefinitions(): array {' . chr(10) .
+            '        return [' . chr(10) .
+            '            ' . implode(',' . chr(10) . '            ', $argumentDefinitionsCode) . ',' . chr(10) .
+            '        ];' . chr(10) .
+            '    }';
+    }
+
     /**
      * Replaces special characters by underscores
      * @see http://www.php.net/manual/en/language.variables.basics.php

src/Core/Compiler/TemplateCompiler.php

@@ -12,6 +12,7 @@
 use TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\NodeInterface;
 use TYPO3Fluid\Fluid\Core\Rendering\RenderingContextInterface;
 use TYPO3Fluid\Fluid\Core\Variables\VariableProviderInterface;
+use TYPO3Fluid\Fluid\Core\ViewHelper\ArgumentDefinition;
 
 /**
  * This interface is returned by \TYPO3Fluid\Fluid\Core\Parser\TemplateParser->parse()
@@ -25,6 +26,11 @@ public function setIdentifier(string $identifier);
 
     public function getIdentifier(): string;
 
+    /**
+     * @return ArgumentDefinition[]
+     */
+    public function getArgumentDefinitions(): array;
+
     /**
      * Render the parsed template with rendering context
      *

src/Core/Parser/ParsedTemplateInterface.php

@@ -13,6 +13,7 @@
 use TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\RootNode;
 use TYPO3Fluid\Fluid\Core\Rendering\RenderingContextInterface;
 use TYPO3Fluid\Fluid\Core\Variables\VariableProviderInterface;
+use TYPO3Fluid\Fluid\Core\ViewHelper\ArgumentDefinition;
 use TYPO3Fluid\Fluid\View;
 
 /**
@@ -26,6 +27,11 @@ class ParsingState implements ParsedTemplateInterface
 {
     protected string $identifier;
 
+    /**
+     * @var array<string, ArgumentDefinition>
+     */
+    protected array $argumentDefinitions = [];
+
     /**
      * Root node reference
      */
@@ -80,6 +86,22 @@ public function getRootNode(): RootNode
         return $this->rootNode;
     }
 
+    /**
+     * @return array<string, ArgumentDefinition>
+     */
+    public function getArgumentDefinitions(): array
+    {
+        return $this->argumentDefinitions;
+    }
+
+    /**
+     * @param array<string, ArgumentDefinition> $argumentDefinitions
+     */
+    public function setArgumentDefinitions(array $argumentDefinitions): void
+    {
+        $this->argumentDefinitions = $argumentDefinitions;
+    }
+
     /**
      * Render the parsed template with rendering context
      *
@@ -111,6 +133,21 @@ public function getNodeFromStack(): NodeInterface
         return $this->nodeStack[count($this->nodeStack) - 1];
     }
 
+    /**
+     * Checks if the specified node type exists in the current stack
+     *
+     * @param class-string $nodeType
+     */
+    public function hasNodeTypeInStack(string $nodeType): bool
+    {
+        foreach ($this->nodeStack as $node) {
+            if ($node instanceof $nodeType) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     /**
      * Pop the top stack element (=remove it) and return it back.
      *

src/Core/Parser/ParsingState.php

@@ -15,6 +15,9 @@
 use TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\ViewHelperNode;
 use TYPO3Fluid\Fluid\Core\Rendering\RenderingContext;
 use TYPO3Fluid\Fluid\Core\Rendering\RenderingContextInterface;
+use TYPO3Fluid\Fluid\Core\Variables\VariableProviderInterface;
+use TYPO3Fluid\Fluid\Core\ViewHelper\ArgumentProcessorInterface;
+use TYPO3Fluid\Fluid\Core\ViewHelper\StrictArgumentProcessor;
 use TYPO3Fluid\Fluid\View\Exception\InvalidSectionException;
 use TYPO3Fluid\Fluid\View\Exception\InvalidTemplateResourceException;
 use TYPO3Fluid\Fluid\ViewHelpers\SectionViewHelper;
@@ -144,6 +147,16 @@ public function render($actionName = null)
 
         if (!$parsedTemplate->hasLayout()) {
             $this->startRendering(self::RENDERING_TEMPLATE, $parsedTemplate, $this->baseRenderingContext);
+            try {
+                // @todo make argument processor configurable with Fluid v5
+                $this->processAndValidateTemplateVariables(
+                    $parsedTemplate,
+                    $this->baseRenderingContext->getVariableProvider(),
+                    new StrictArgumentProcessor(),
+                );
+            } catch (Exception $validationError) {
+                return $renderingContext->getErrorHandler()->handleViewError($validationError);
+            }
             $output = $parsedTemplate->render($this->baseRenderingContext);
             $this->stopRendering();
         } else {
@@ -159,6 +172,16 @@ function ($parent, TemplatePaths $paths) use ($layoutName) {
                 return $error->getSource();
             }
             $this->startRendering(self::RENDERING_LAYOUT, $parsedTemplate, $this->baseRenderingContext);
+            try {
+                // @todo make argument processor configurable with Fluid v5
+                $this->processAndValidateTemplateVariables(
+                    $parsedLayout,
+                    $this->baseRenderingContext->getVariableProvider(),
+                    new StrictArgumentProcessor(),
+                );
+            } catch (Exception $validationError) {
+                return $renderingContext->getErrorHandler()->handleViewError($validationError);
+            }
             $output = $parsedLayout->render($this->baseRenderingContext);
             $this->stopRendering();
         }
@@ -286,6 +309,16 @@ function ($parent, TemplatePaths $paths) use ($partialName) {
         if ($sectionName !== null) {
             $output = $this->renderSection($sectionName, $variables, $ignoreUnknown);
         } else {
+            try {
+                // @todo make argument processor configurable with Fluid v5
+                $this->processAndValidateTemplateVariables(
+                    $parsedPartial,
+                    $renderingContext->getVariableProvider(),
+                    new StrictArgumentProcessor(),
+                );
+            } catch (Exception $validationError) {
+                return $renderingContext->getErrorHandler()->handleViewError($validationError);
+            }
             $output = $parsedPartial->render($renderingContext);
         }
         $this->stopRendering();
@@ -362,4 +395,42 @@ protected function getCurrentRenderingContext()
         $currentRendering = end($this->renderingStack);
         return !empty($currentRendering['renderingContext']) ? $currentRendering['renderingContext'] : $this->baseRenderingContext;
     }
+
+    protected function processAndValidateTemplateVariables(
+        ParsedTemplateInterface $parsedTemplate,
+        VariableProviderInterface $variableProvider,
+        ArgumentProcessorInterface $argumentProcessor,
+    ): void {
+        $renderingTypeLabel = match ($this->getCurrentRenderingType()) {
+            self::RENDERING_PARTIAL => 'partial',
+            self::RENDERING_TEMPLATE => 'template',
+            self::RENDERING_LAYOUT => 'layout',
+        };
+        foreach ($parsedTemplate->getArgumentDefinitions() as $argumentDefinition) {
+            $argumentName = $argumentDefinition->getName();
+            if ($variableProvider->exists($argumentName)) {
+                $processedValue = $argumentProcessor->process($variableProvider->get($argumentName), $argumentDefinition);
+                if (!$argumentProcessor->isValid($processedValue, $argumentDefinition)) {
+                    throw new Exception(sprintf(
+                        'The argument "%s" for %s "%s" is registered with type "%s", but the provided value is of type "%s".',
+                        $argumentName,
+                        $renderingTypeLabel,
+                        $parsedTemplate->getIdentifier(),
+                        $argumentDefinition->getType(),
+                        is_object($processedValue) ? get_class($processedValue) : gettype($processedValue),
+                    ), 1746637333);
+                }
+                $variableProvider->add($argumentName, $processedValue);
+            } elseif ($argumentDefinition->isRequired()) {
+                throw new Exception(sprintf(
+                    'The argument "%s" for %s "%s" is required, but was not provided.',
+                    $argumentName,
+                    $renderingTypeLabel,
+                    $parsedTemplate->getIdentifier(),
+                ), 1746637334);
+            } else {
+                $variableProvider->add($argumentName, $argumentDefinition->getDefaultValue());
+            }
+        }
+    }
 }