Merge pull request #393 from CPS-IT/feature/1.x/view

[!!!][FEATURE] Introduce `HandlebarsView` and require it in renderers

Classes/DataProcessing/SimpleProcessor.php

@@ -25,6 +25,7 @@
 
 use Fr\Typo3Handlebars\Exception\InvalidTemplateFileException;
 use Fr\Typo3Handlebars\Renderer\Renderer;
+use Fr\Typo3Handlebars\Renderer\Template\View\HandlebarsView;
 use Fr\Typo3Handlebars\Traits\ErrorHandlingTrait;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\DependencyInjection\Attribute\Autoconfigure;
@@ -51,8 +52,12 @@ public function __construct(
     public function process(string $content, array $configuration): string
     {
         try {
-            $templatePath = $this->getTemplatePath($configuration);
-            return $this->renderer->render($templatePath, $this->contentObjectRenderer?->data ?? []);
+            $view = new HandlebarsView(
+                $this->getTemplatePath($configuration),
+                $this->contentObjectRenderer?->data ?? [],
+            );
+
+            return $this->renderer->render($view);
         } catch (InvalidTemplateFileException $exception) {
             $this->handleError($exception);
             return '';

Classes/Event/AfterRenderingEvent.php

@@ -34,14 +34,14 @@
 final class AfterRenderingEvent
 {
     public function __construct(
-        private readonly string $templatePath,
+        private readonly Renderer\Template\View\HandlebarsView $view,
         private string $content,
         private readonly Renderer\Renderer $renderer,
     ) {}
 
-    public function getTemplatePath(): string
+    public function getView(): Renderer\Template\View\HandlebarsView
     {
-        return $this->templatePath;
+        return $this->view;
     }
 
     public function getContent(): string

Classes/Event/BeforeRenderingEvent.php

@@ -37,14 +37,14 @@ final class BeforeRenderingEvent
      * @param array<string|int, mixed> $variables
      */
     public function __construct(
-        private readonly string $templatePath,
+        private readonly Renderer\Template\View\HandlebarsView $view,
         private array $variables,
         private readonly Renderer\Renderer $renderer,
     ) {}
 
-    public function getTemplatePath(): string
+    public function getView(): Renderer\Template\View\HandlebarsView
     {
-        return $this->templatePath;
+        return $this->view;
     }
 
     /**

Classes/Exception/PartialPathIsNotResolvable.php

@@ -31,10 +31,16 @@
  */
 final class PartialPathIsNotResolvable extends Exception
 {
-    public function __construct(string $path)
+    public function __construct(string $path, ?string $format = null)
     {
+        if ($format !== null) {
+            $formatMessage = sprintf(' with format "%s"', $format);
+        } else {
+            $formatMessage = '';
+        }
+
         parent::__construct(
-            \sprintf('The partial path "%s" cannot be resolved.', $path),
+            \sprintf('The partial path "%s"%s cannot be resolved.', $path, $formatMessage),
             1736254715,
         );
     }

Classes/Exception/TemplateFileIsInvalid.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the TYPO3 CMS extension "handlebars".
+ *
+ * Copyright (C) 2025 Elias Häußler <e.haeussler@familie-redlich.de>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+namespace Fr\Typo3Handlebars\Exception;
+
+/**
+ * TemplateFileIsInvalid
+ *
+ * @author Elias Häußler <e.haeussler@familie-redlich.de>
+ * @license GPL-2.0-or-later
+ */
+final class TemplateFileIsInvalid extends Exception
+{
+    public function __construct(string $file)
+    {
+        parent::__construct(
+            \sprintf('The template file "%s" is invalid or does not exist.', $file),
+            1736333208,
+        );
+    }
+}

Classes/Exception/TemplateFormatIsNotSupported.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the TYPO3 CMS extension "handlebars".
+ *
+ * Copyright (C) 2025 Elias Häußler <e.haeussler@familie-redlich.de>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+namespace Fr\Typo3Handlebars\Exception;
+
+/**
+ * TemplateFormatIsNotSupported
+ *
+ * @author Elias Häußler <e.haeussler@familie-redlich.de>
+ * @license GPL-2.0-or-later
+ */
+final class TemplateFormatIsNotSupported extends Exception
+{
+    public function __construct(string $format)
+    {
+        parent::__construct(
+            sprintf('The format "%s" is not supported by this template resolver.', $format),
+            1736349135,
+        );
+    }
+}

Classes/Exception/TemplatePathIsNotResolvable.php

@@ -31,10 +31,16 @@
  */
 final class TemplatePathIsNotResolvable extends Exception
 {
-    public function __construct(string $path)
+    public function __construct(string $path, ?string $format = null)
     {
+        if ($format !== null) {
+            $formatMessage = \sprintf(' with format "%s"', $format);
+        } else {
+            $formatMessage = '';
+        }
+
         parent::__construct(
-            \sprintf('The template path "%s" cannot be resolved.', $path),
+            \sprintf('The template path "%s"%s cannot be resolved.', $path, $formatMessage),
             1736254772,
         );
     }

Classes/Exception/ViewIsNotProperlyInitialized.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the TYPO3 CMS extension "handlebars".
+ *
+ * Copyright (C) 2025 Elias Häußler <e.haeussler@familie-redlich.de>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+namespace Fr\Typo3Handlebars\Exception;
+
+/**
+ * ViewIsNotProperlyInitialized
+ *
+ * @author Elias Häußler <e.haeussler@familie-redlich.de>
+ * @license GPL-2.0-or-later
+ */
+final class ViewIsNotProperlyInitialized extends Exception
+{
+    public function __construct()
+    {
+        parent::__construct(
+            'The Handlebars view is not properly initialized. Provide either template path or template source.',
+            1736332788,
+        );
+    }
+}

Classes/Renderer/HandlebarsRenderer.php

@@ -61,57 +61,48 @@ public function __construct(
         $this->debugMode = $this->isDebugModeEnabled();
     }
 
-    public function render(string $templatePath, array $data = []): string
+    public function render(Template\View\HandlebarsView $view): string
     {
         try {
-            return $this->processRendering($templatePath, $data);
-        } catch (Exception\InvalidTemplateFileException | Exception\TemplateCompilationException | Exception\TemplatePathIsNotResolvable $exception) {
+            return $this->processRendering($view);
+        } catch (Exception\TemplateCompilationException | Exception\TemplateFileIsInvalid | Exception\TemplateFormatIsNotSupported | Exception\TemplatePathIsNotResolvable | Exception\ViewIsNotProperlyInitialized $exception) {
             $this->logger->critical($exception->getMessage(), ['exception' => $exception]);
 
             return '';
         }
     }
 
     /**
-     * @param array<string|int, mixed> $variables
-     * @throws Exception\InvalidTemplateFileException
-     * @throws Exception\TemplateCompilationException
+     * @throws Exception\TemplateFileIsInvalid
+     * @throws Exception\TemplateFormatIsNotSupported
      * @throws Exception\TemplatePathIsNotResolvable
+     * @throws Exception\ViewIsNotProperlyInitialized
      */
-    protected function processRendering(string $templatePath, array $variables): string
+    protected function processRendering(Template\View\HandlebarsView $view): string
     {
-        $fullTemplatePath = $this->templateResolver->resolveTemplatePath($templatePath);
-        $template = file_get_contents($fullTemplatePath);
-
-        // Throw exception if template file is invalid
-        if ($template === false) {
-            throw new Exception\InvalidTemplateFileException($fullTemplatePath, 1606217313);
-        }
+        $compileResult = $this->compile($view);
 
         // Early return if template is empty
-        if (trim($template) === '') {
+        if ($compileResult === null) {
             return '';
         }
 
         // Merge variables with default variables
-        $mergedVariables = array_merge($this->variableBag->get(), $variables);
-
-        // Compile template
-        $compileResult = $this->compile($template);
-        $renderer = $this->prepareCompileResult($compileResult);
+        $mergedVariables = array_merge($this->variableBag->get(), $view->getVariables());
 
         // Dispatch before rendering event
-        $beforeRenderingEvent = new Event\BeforeRenderingEvent($fullTemplatePath, $mergedVariables, $this);
+        $beforeRenderingEvent = new Event\BeforeRenderingEvent($view, $mergedVariables, $this);
         $this->eventDispatcher->dispatch($beforeRenderingEvent);
 
         // Render content
+        $renderer = $this->prepareCompileResult($compileResult);
         $content = $renderer($beforeRenderingEvent->getVariables(), [
             'debug' => Runtime::DEBUG_TAGS_HTML,
             'helpers' => $this->helperRegistry->getAll(),
         ]);
 
         // Dispatch after rendering event
-        $afterRenderingEvent = new Event\AfterRenderingEvent($fullTemplatePath, $content, $this);
+        $afterRenderingEvent = new Event\AfterRenderingEvent($view, $content, $this);
         $this->eventDispatcher->dispatch($afterRenderingEvent);
 
         return $afterRenderingEvent->getContent();
@@ -120,16 +111,25 @@ protected function processRendering(string $templatePath, array $variables): str
     /**
      * Compile given template by LightnCandy compiler.
      *
-     * @param string $template Raw template to be compiled
-     * @return string The compiled template
-     * @throws Exception\TemplateCompilationException() if template compilation fails and errors are not yet handled by compiler
+     * @throws Exception\TemplateFileIsInvalid
+     * @throws Exception\TemplateFormatIsNotSupported
+     * @throws Exception\TemplatePathIsNotResolvable
+     * @throws Exception\ViewIsNotProperlyInitialized
      */
-    protected function compile(string $template): string
+    protected function compile(Template\View\HandlebarsView $view): ?string
     {
+        $template = $view->getTemplate($this->templateResolver);
+
+        // Early return if template is empty
+        if (\trim($template) === '') {
+            return null;
+        }
+
         // Disable cache if debugging is enabled or caching is disabled
-        $cache = $this->cache;
         if ($this->debugMode || $this->isCachingDisabled()) {
             $cache = new Cache\NullCache();
+        } else {
+            $cache = $this->cache;
         }
 
         // Get compile result from cache
@@ -239,6 +239,7 @@ protected function getHelperStubs(): array
      * @param string $name Name of the partial to be resolved
      * @return string|null Partial file contents if partial could be resolved, `null` otherwise
      * @throws Exception\PartialPathIsNotResolvable
+     * @throws Exception\TemplateFormatIsNotSupported
      */
     public function resolvePartial(array $context, string $name): ?string
     {

Classes/Renderer/Helper/ExtendHelper.php

@@ -60,9 +60,11 @@ public function render(Context\HelperContext $context): string
         $renderingContext['_layoutStack'][] = $handlebarsLayout;
 
         // Merge data with supplied data
-        $renderData = array_replace_recursive($renderingContext, $customContext, $context->hash);
+        $variables = array_replace_recursive($renderingContext, $customContext, $context->hash);
 
         // Render layout with merged data
-        return $this->renderer->render($name, $renderData);
+        return $this->renderer->render(
+            new Renderer\Template\View\HandlebarsView($name, $variables),
+        );
     }
 }

Classes/Renderer/Helper/RenderHelper.php

@@ -86,7 +86,9 @@ public function render(Context\HelperContext $context): SafeString
         if ($renderUncached) {
             $content = $this->registerUncachedTemplateBlock($name, $subContext);
         } else {
-            $content = $this->renderer->render($name, $subContext);
+            $content = $this->renderer->render(
+                new Renderer\Template\View\HandlebarsView($name, $subContext),
+            );
         }
 
         return new SafeString($content);

Classes/Renderer/Renderer.php

@@ -31,8 +31,5 @@
  */
 interface Renderer
 {
-    /**
-     * @param array<string|int, mixed> $data
-     */
-    public function render(string $templatePath, array $data = []): string;
+    public function render(Template\View\HandlebarsView $view): string;
 }