[FEATURE] <f:push> ViewHelper

Documentation/ViewHelpers/Fluid/Push.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/PushViewHelper.php
+
+:edit-on-github-link: https://github.com/TYPO3/Fluid/edit/main/src/ViewHelpers/PushViewHelper.php
+:navigation-title: push
+
+..  include:: /Includes.rst.txt
+
+..  _typo3fluid-fluid-push:
+
+==========================
+Push ViewHelper `<f:push>`
+==========================
+
+.. ..  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/Push>` instead.
+
+..  typo3:viewhelper:: push
+    :source: ../Fluid.json

src/ViewHelpers/PushViewHelper.php

@@ -0,0 +1,78 @@
+<?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\ViewHelpers;
+
+use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;
+
+/**
+ * Add a value to a given array variable. If the variable is null or empty,
+ * it will be initialized as an empty array.
+ *
+ *  Examples
+ *  ========
+ *
+ *  Add a value to the end of an array
+ *  ----------------------------------
+ *
+ *  ::
+ *
+ *      <f:variable name="tags"/>
+ *      <f:for each="{newsItem.tags}" as="tag">
+ *          <f:push name="tags" value="{tag.title}" />
+ *      </f:for>
+ *
+ *  Add a value with a key to an array
+ *  ----------------------------------
+ *
+ *  If the key already exists, the value will be overridden.
+ *
+ *  ::
+ *
+ *      <f:push name="tags" key="some-key" value="some-value" />
+ */
+final class PushViewHelper extends AbstractViewHelper
+{
+    public function initializeArguments(): void
+    {
+        $this->registerArgument(
+            'value',
+            'mixed',
+            'Value to push to specified array variable. If not in arguments then taken from tag content.',
+        );
+        $this->registerArgument(
+            'name',
+            'string',
+            'Name of variable to extend.',
+            true,
+        );
+        $this->registerArgument(
+            'key',
+            'string',
+            'Key that should be used in the array',
+        );
+    }
+
+    public function render(): void
+    {
+        $value = $this->arguments['value'] ?? $this->renderChildren();
+
+        $variable = $this->renderingContext->getVariableProvider()->get($this->arguments['name']);
+        if (! \is_array($variable)) {
+            $variable = [];
+        }
+        if ($this->arguments['key']) {
+            $variable[$this->arguments['key']] = $value;
+        } else {
+            $variable[] = $value;
+        }
+
+        $this->renderingContext->getVariableProvider()->add($this->arguments['name'], $variable);
+    }
+}

tests/Functional/ViewHelpers/PushViewHelperTest.php

@@ -0,0 +1,91 @@
+<?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\ViewHelpers;
+
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+use TYPO3Fluid\Fluid\Tests\Functional\AbstractFunctionalTestCase;
+use TYPO3Fluid\Fluid\View\TemplateView;
+
+final class PushViewHelperTest extends AbstractFunctionalTestCase
+{
+    public static function renderDataProvider(): iterable
+    {
+        $simpleArray = ['a', 'b', 'c', 'd'];
+        $arrayWithKeys = [
+            'keyA' => 'a',
+            'keyB' => 'b',
+            'keyC' => 'c',
+            'keyD' => 'd',
+        ];
+
+        yield 'simple array' => [
+            'arguments' => ['inputArray' => $simpleArray],
+            'src' => '<f:variable name="resultArray"></f:variable>'
+                . '<f:for each="{inputArray}" as="value">'
+                . '<f:push name="resultArray" value="{value}" />'
+                . '</f:for>',
+            'expectation' => ['a', 'b', 'c', 'd'],
+        ];
+
+        yield 'simple array (inline)' => [
+            'arguments' => ['inputArray' => $simpleArray],
+            'src' => '{f:variable(name: "resultArray")}'
+                . '{item -> f:push(name: "resultArray") -> f:for(each: "{inputArray}", as: "item")}',
+            'expectation' => ['a', 'b', 'c', 'd'],
+        ];
+
+        yield 'array with keys' => [
+            'arguments' => ['inputArray' => $arrayWithKeys],
+            'src' => '<f:variable name="resultArray"></f:variable>'
+                . '<f:for each="{inputArray}" as="value" key="key">'
+                . '<f:push name="resultArray" value="{value}" key="{key}"/>'
+                . '</f:for>',
+            'expectation' => [
+                'keyA' => 'a',
+                'keyB' => 'b',
+                'keyC' => 'c',
+                'keyD' => 'd',
+            ],
+        ];
+
+        yield 'variable name not defined' => [
+            'arguments' => ['inputArray' => $arrayWithKeys],
+            'src' => '<f:for each="{inputArray}" as="value" key="key">'
+                . '<f:push name="resultArray" value="{value}" key="{key}"/>'
+                . '</f:for>',
+            'expectation' => [
+                'keyA' => 'a',
+                'keyB' => 'b',
+                'keyC' => 'c',
+                'keyD' => 'd',
+            ],
+        ];
+    }
+
+    #[Test]
+    #[DataProvider('renderDataProvider')]
+    public function render(array $arguments, string $src, array $expectation): void
+    {
+        $view = new TemplateView();
+        $view->getRenderingContext()->setCache(self::$cache);
+        $view->getRenderingContext()->getTemplatePaths()->setTemplateSource($src);
+        $view->assignMultiple($arguments);
+        $view->render();
+        self::assertSame($expectation, $view->getRenderingContext()->getVariableProvider()->get('resultArray'));
+
+        $view = new TemplateView();
+        $view->getRenderingContext()->setCache(self::$cache);
+        $view->getRenderingContext()->getTemplatePaths()->setTemplateSource($src);
+        $view->assignMultiple($arguments);
+        $view->render();
+        self::assertSame($expectation, $view->getRenderingContext()->getVariableProvider()->get('resultArray'));
+    }
+}