[FEATURE] Introduce argument definitions for templates and partials

s2b · s2b · commit 7b478e314371 · 2025-05-02T19:31:18.000+02:00
diff --git a/Documentation/ViewHelpers/Fluid.json b/Documentation/ViewHelpers/Fluid.json
diff --git a/Documentation/ViewHelpers/Fluid/Argument.rst b/Documentation/ViewHelpers/Fluid/Argument.rst
@@ -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
diff --git a/examples/Resources/Private/Singles/TemplateArguments.html b/examples/Resources/Private/Singles/TemplateArguments.html
@@ -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}
diff --git a/examples/example_templatearguments.php b/examples/example_templatearguments.php
@@ -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);
diff --git a/src/Core/Compiler/AbstractCompiledTemplate.php b/src/Core/Compiler/AbstractCompiledTemplate.php
@@ -34,6 +34,11 @@ public function getVariableContainer(): VariableProviderInterface
         return new StandardVariableProvider();
     }
 
+    public function getArgumentDefinitions(): array
+    {
+        return [];
+    }
+
     /**
      * Render the parsed template with rendering context
      *
diff --git a/src/Core/Compiler/TemplateCompiler.php b/src/Core/Compiler/TemplateCompiler.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,30 @@ 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)',
+                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),
+            ),
+            $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
diff --git a/src/Core/Parser/ParsedTemplateInterface.php b/src/Core/Parser/ParsedTemplateInterface.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()
@@ -23,6 +24,11 @@ public function setIdentifier(string $identifier);
 
     public function getIdentifier(): string;
 
+    /**
+     * @return ArgumentDefinition[]
+     */
+    public function getArgumentDefinitions(): array;
+
     /**
      * Render the parsed template with rendering context
      *
diff --git a/src/Core/Parser/ParsingState.php b/src/Core/Parser/ParsingState.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;
 
 /**
@@ -24,6 +25,11 @@ class ParsingState implements ParsedTemplateInterface
 {
     protected string $identifier;
 
+    /**
+     * @var array<string, ArgumentDefinition>
+     */
+    protected array $argumentDefinitions = [];
+
     /**
      * Root node reference
      */
@@ -78,6 +84,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
      *
@@ -109,6 +131,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.
      *
diff --git a/src/ViewHelpers/ArgumentViewHelper.php b/src/ViewHelpers/ArgumentViewHelper.php
@@ -0,0 +1,139 @@
+<?php
+
+/*
+ * This file belongs to the package "TYPO3 Fluid".
+ * See LICENSE.txt that was shipped with this package.
+ */
+
+namespace TYPO3Fluid\Fluid\ViewHelpers;
+
+use TYPO3Fluid\Fluid\Core\Compiler\TemplateCompiler;
+use TYPO3Fluid\Fluid\Core\Parser\ParsingState;
+use TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\NodeInterface;
+use TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\ViewHelperNode;
+use TYPO3Fluid\Fluid\Core\Rendering\RenderingContext;
+use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;
+use TYPO3Fluid\Fluid\Core\ViewHelper\ArgumentDefinition;
+
+/**
+ * ``f:argument`` allows to define requirements and type constraints to variables that
+ * are provided to templates and partials. This can be very helpful to document how
+ * a template or partial is supposed to be used and which input variables are required.
+ *
+ * These requirements are enforced during rendering of the template or partial:
+ * If an argument is defined with this ViewHelper which isn't marked as ``optional``,
+ * an exception will be thrown if that variable isn't present during rendering.
+ * If a variable doesn't match the specified type and can't be converted automatically,
+ * an exception will be thrown as well.
+ *
+ * Note that ``f:argument`` ViewHelpers must be used at the root level of the
+ * template, and can't be nested into other ViewHelpers. Also, the usage of variables
+ * in any of its arguments is not possible (e. g. you can't define an argument name
+ * by using a variable).
+ *
+ * Example
+ * ========
+ *
+ * For the following partial:
+ *
+ * .. code-block:: xml
+ *
+ *    <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}
+ *
+ * The following render calls will be successful:
+ *
+ * .. code-block:: xml
+ *
+ *    <!-- All arguments supplied -->
+ *    <f:render partial="MyPartial" arguments="{title: 'My title', tags: {0: 'tag1', 1: 'tag2'}, user: 'me'}" />
+ *    <!-- "user" will fall back to default value -->
+ *    <f:render partial="MyPartial" arguments="{title: 'My title', tags: {0: 'tag1', 1: 'tag2'}}" />
+ *    <!-- "tags" will be "null", "user" will fall back to default value -->
+ *    <f:render partial="MyPartial" arguments="{title: 'My title'}" />
+ *
+ * The following render calls will result in an exception:
+ *
+ * .. code-block:: xml
+ *
+ *    <!-- required "title" has not been supplied -->
+ *    <f:render partial="MyPartial" />
+ *    <!-- "user" has been supplied as array, not as string -->
+ *    <f:render partial="MyPartial" arguments="{title: 'My title', user: {firstName: 'Jane', lastName: 'Doe'}}" />
+ *
+ * @api
+ */
+final class ArgumentViewHelper extends AbstractViewHelper
+{
+    /**
+     * No need to add escaping nodes since the ViewHelper doesn't output anything
+     */
+    protected $escapeOutput = false;
+
+    public function initializeArguments(): void
+    {
+        $this->registerArgument('name', 'string', 'name of the template argument', true);
+        $this->registerArgument('type', 'string', 'type of the template argument', true);
+        $this->registerArgument('description', 'string', 'description of the template argument');
+        $this->registerArgument('optional', 'boolean', 'true if the defined argument should be optional', false, false);
+        $this->registerArgument('default', 'mixed', 'default value for optional argument');
+    }
+
+    public function render(): string
+    {
+        return '';
+    }
+
+    public function compile($argumentsName, $closureName, &$initializationPhpCode, ViewHelperNode $node, TemplateCompiler $compiler): string
+    {
+        return '\'\'';
+    }
+
+    public static function nodeInitializedEvent(ViewHelperNode $node, array $arguments, ParsingState $parsingState): void
+    {
+        // Create static values of supplied arguments. A new empty rendering context is used here
+        // because argument definitions shouldn't be dependent on any variables in the template.
+        // Any variables that are used anyway (e. g. in default values) will be interpreted as "null"
+        $emptyRenderingContext = new RenderingContext();
+        $evaluatedArguments = array_map(
+            static fn(NodeInterface $node): mixed => $node->evaluate($emptyRenderingContext),
+            $arguments,
+        );
+        $argumentName = (string)$evaluatedArguments['name'];
+
+        // Make sure that arguments are not nested into other ViewHelpers as this might create confusion
+        if ($parsingState->hasNodeTypeInStack(ViewHelperNode::class)) {
+            throw new \TYPO3Fluid\Fluid\Core\Parser\Exception(sprintf(
+                'Template argument "%s" needs to be defined at the root level of the template, not within a ViewHelper.',
+                $argumentName,
+            ), 1744908510);
+        }
+
+        // Make sure that this argument hasn't already been defined in the template
+        $argumentDefinitions = $parsingState->getArgumentDefinitions();
+        if (isset($argumentDefinitions[$argumentName])) {
+            throw new \TYPO3Fluid\Fluid\Core\Parser\Exception(sprintf(
+                'Template argument "%s" has been defined multiple times.',
+                $argumentName,
+            ), 1744908509);
+        }
+
+        // Create argument definition to be interpreted later during rendering
+        // This will also be written to the cache by the TemplateCompiler
+        $argumentDefinitions[$argumentName] = new ArgumentDefinition(
+            $argumentName,
+            (string)$evaluatedArguments['type'],
+            array_key_exists('description', $evaluatedArguments) ? (string)$evaluatedArguments['description'] : '',
+            array_key_exists('optional', $evaluatedArguments) ? !$evaluatedArguments['optional'] : false,
+            array_key_exists('default', $evaluatedArguments) ? $evaluatedArguments['default'] : null,
+        );
+        $parsingState->setArgumentDefinitions($argumentDefinitions);
+    }
+}
diff --git a/tests/Functional/Core/Parser/ParsingErrorsTest.php b/tests/Functional/Core/Parser/ParsingErrorsTest.php
diff --git a/tests/Functional/ExamplesTest.php b/tests/Functional/ExamplesTest.php
diff --git a/tests/Functional/Fixtures/Various/ParsedTemplateImplementationFixture.php b/tests/Functional/Fixtures/Various/ParsedTemplateImplementationFixture.php

Original file line number	Diff line number	Diff line change
`@@ -34,6 +34,11 @@ public function getVariableContainer(): VariableProviderInterface`
`34`	`34`	`return new StandardVariableProvider();`
`35`	`35`	`}`
`36`	`36`
	`37`	`+ public function getArgumentDefinitions(): array`
	`38`	`+ {`
	`39`	`+ return [];`
	`40`	`+ }`
	`41`	`+`
`37`	`42`	`/**`
`38`	`43`	`* Render the parsed template with rendering context`
`39`	`44`	`*`