feat(view): standalone TempestViewRenderer support (#1686)

Author: brendt

docs/1-essentials/02-views.md

@@ -622,6 +622,83 @@ Tempest views are always compiled to plain PHP code before being rendered. Durin
 
 During deployments, that cache must be cleared in order to not serve outdated views to users. You may do that by running `tempest view:clear` on every deploy.
 
+## Tempest View as a standalone engine
+
+Tempest View is also designed to be used as a standalone engine in whatever PHP project you want. Start by requiring `tempest/view`:
+
+```sh
+composer require tempest/view
+```
+
+As a bare minimum setup, you can create an instance of the renderer by calling `TempestViewRenderer::make()`:
+
+```php
+use Tempest\View\Renderers\TempestViewRenderer;
+use function Tempest\view;
+
+$renderer = TempestViewRenderer::make();
+
+$html = $renderer->render(view('home.view.php', name: 'Brent'));
+```
+
+If, however, you want view component support, you will need to provide a `ViewConfig` object as well:
+
+```php
+use Tempest\View\Renderers\TempestViewRenderer;
+use Tempest\View\ViewConfig;
+
+$config = new ViewConfig()->addViewComponents(
+    __DIR__ . '/components/x-base.view.php',
+    __DIR__ . '/components/x-footer.view.php',
+    __DIR__ . '/components/x-header.view.php',
+);
+
+$renderer = TempestViewRenderer::make($config);
+```
+
+If you want to rely on Tempest's discovery to find view components, you can boot a minimal version of Tempest, and resolve the view renderer from the container:
+
+```php
+use Tempest\Core\Tempest;
+use Tempest\View\ViewRenderer;
+
+$container = Tempest::boot(__DIR__);
+
+$html = $container->get(ViewRenderer::class)->render(
+    view('home.view.php', name: 'Brent')
+);
+```
+
+You can choose whichever way you prefer. Chances are that, if you use the minimal setup without booting Tempest, you'll want to add a custom view component loader. That's up to you to implement then.
+
+### A note on caching
+
+When you're using the minimal setup, view caching can be enabled by passing in a `$viewCache` paremeter into `TempestViewRenderer::make()`:
+
+```php
+use Tempest\View\Renderers\TempestViewRenderer;
+use Tempest\View\ViewCache;
+
+$renderer = TempestViewRenderer::make(
+    cache: ViewCache::enabled(),
+);
+```
+
+It's recommended to turn view caching on in production environments. To clear the view cache, you can call the `clear()` method on the `ViewCache` object:
+
+```php
+use Tempest\View\Renderers\TempestViewRenderer;
+use Tempest\View\ViewCache;
+
+$viewCache = ViewCache::enabled();
+
+$viewCache->clear();
+
+$renderer = TempestViewRenderer::make(
+    cache: $viewCache,
+);
+```
+
 ## Separate view directories
 
 View files can live in any directory that is discoverable by Tempest. That means: a directory with a PSR-4 namespace associated with it. If you want your view files to live outside of `src` or `app`, you can add a namespace for it in composer.json:
@@ -637,7 +714,7 @@ View files can live in any directory that is discoverable by Tempest. That means
 
 Don't forget to run `composer up` after making changes to your composer.json file.
 
-Note that view files themselves don't need a namespace; this namespace is only here to tell Tempest that `views/` is a directory it should scan. If you want to add a class in the `Views` namespace (like, for example, a [custom view object](/2.x/essentials/views#using-dedicated-view-objects)), then that is possible as well. 
+Note that view files themselves don't need a namespace; this namespace is only here to tell Tempest that `views/` is a directory it should scan. If you want to add a class in the `Views` namespace (like, for example, a [custom view object](/2.x/essentials/views#using-dedicated-view-objects)), then that is possible as well.
 
 ## Using other engines
 

docs/5-extra-topics/02-standalone-components.md

@@ -97,25 +97,7 @@ ld($variable);
 
 ## `tempest/view`
 
-Tempest View can be used as a standalone package:
-
-```
-composer require tempest/view
-```
-
-```php
-$container = Tempest::boot(__DIR__);
-
-$view = view(__DIR__ . '/src/b.view.php');
-
-echo $container->get(ViewRenderer::class)->render($view);
-```
-
-There are a couple of notes to make when running Tempest View as a standalone component:
-
-- Any view files and components will be discovered and must be in a directory with a valid PSR-4 namespace. View files themselves don't need to have a namespace, though.
-- View files are compiled and cached. You can manually enable or disable this cache by setting the `{env}{:hl-keyword:VIEW_CACHE:}` environment variable to `true` or `false`. By default, the view cache is disabled.
-- Optionally, you can require `tempest/console`, which will provide you with the `vendor/bin/tempest view:clear` command to clear view caches. If you don't install `tempest/console`, you'll have to manually clear view caches on deployment by removing the `.tempest/cache/views` directory.
+Tempest View can be used as a standalone package. You can read about how to use it [here](/2.x/essentials/views#tempest-view-as-a-standalone-engine).
 
 ## `tempest/event-bus`
 

packages/view/src/Elements/ElementFactory.php

@@ -4,8 +4,7 @@
 
 namespace Tempest\View\Elements;
 
-use Tempest\Container\Container;
-use Tempest\Core\AppConfig;
+use Tempest\Core\Environment;
 use Tempest\View\Attributes\PhpAttribute;
 use Tempest\View\Element;
 use Tempest\View\Parser\TempestViewCompiler;
@@ -18,14 +17,13 @@ final class ElementFactory
 {
     private TempestViewCompiler $compiler;
 
+    private(set) bool $isHtml = false;
+
     public function __construct(
-        private readonly AppConfig $appConfig,
         private readonly ViewConfig $viewConfig,
-        private readonly Container $container,
+        private readonly Environment $environment,
     ) {}
 
-    private(set) bool $isHtml = false;
-
     public function setViewCompiler(TempestViewCompiler $compiler): self
     {
         $this->compiler = $compiler;
@@ -93,7 +91,7 @@ private function makeElement(Token $token, ?Element $parent): ?Element
         if ($viewComponentClass = $this->viewConfig->viewComponents[$token->tag] ?? null) {
             $element = new ViewComponentElement(
                 token: $token,
-                environment: $this->appConfig->environment,
+                environment: $this->environment,
                 compiler: $this->compiler,
                 viewComponent: $viewComponentClass,
                 attributes: $attributes,

packages/view/src/Exceptions/ViewComponentPathWasInvalid.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Tempest\View\Exceptions;
+
+use Exception;
+
+final class ViewComponentPathWasInvalid extends Exception
+{
+    public function __construct(string $fileName)
+    {
+        parent::__construct("View component file names must start with `x-` and end with `.view.php`, instead got `{$fileName}`.");
+    }
+}

packages/view/src/Exceptions/ViewComponentPathWasNotFound.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Tempest\View\Exceptions;
+
+use Exception;
+
+final class ViewComponentPathWasNotFound extends Exception
+{
+    public function __construct(string $fileName)
+    {
+        parent::__construct("There's no view component file at `{$fileName}`.");
+    }
+}

packages/view/src/Initializers/ElementFactoryInitializer.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Tempest\View\Initializers;
+
+use Tempest\Container\Container;
+use Tempest\Container\Initializer;
+use Tempest\Container\Singleton;
+use Tempest\Core\AppConfig;
+use Tempest\View\Elements\ElementFactory;
+use Tempest\View\ViewConfig;
+
+final class ElementFactoryInitializer implements Initializer
+{
+    #[Singleton]
+    public function initialize(Container $container): ElementFactory
+    {
+        return new ElementFactory(
+            $container->get(ViewConfig::class),
+            $container->get(AppConfig::class)->environment,
+        );
+    }
+}

packages/view/src/ViewCacheInitializer.php renamed to packages/view/src/Initializers/ViewCacheInitializer.php

@@ -1,11 +1,12 @@
 <?php
 
-namespace Tempest\View;
+namespace Tempest\View\Initializers;
 
 use Tempest\Container\Container;
 use Tempest\Container\Initializer;
 use Tempest\Container\Singleton;
 use Tempest\Core\AppConfig;
+use Tempest\View\ViewCache;
 
 use function Tempest\env;
 

packages/view/src/Parser/TempestViewCompiler.php

@@ -4,7 +4,6 @@
 
 namespace Tempest\View\Parser;
 
-use Tempest\Core\Kernel;
 use Tempest\Discovery\DiscoveryLocation;
 use Tempest\Support\Filesystem;
 use Tempest\View\Attribute;
@@ -30,7 +29,8 @@
     public function __construct(
         private ElementFactory $elementFactory,
         private AttributeFactory $attributeFactory,
-        private Kernel $kernel,
+        /** @var DiscoveryLocation[] */
+        private array $discoveryLocations = [],
     ) {}
 
     public function compile(string|View $view): string
@@ -86,7 +86,7 @@ private function retrieveTemplate(string|View $view): string
 
         $searchPathOptions = [
             ...$searchPathOptions,
-            ...arr($this->kernel->discoveryLocations)
+            ...arr($this->discoveryLocations)
                 ->map(fn (DiscoveryLocation $discoveryLocation) => path($discoveryLocation->path, $path)->toString())
                 ->toArray(),
         ];

packages/view/src/Renderers/TempestViewRenderer.php

@@ -6,8 +6,11 @@
 
 use Stringable;
 use Tempest\Container\Container;
+use Tempest\Core\Environment;
 use Tempest\Support\Filesystem;
 use Tempest\Support\Html\HtmlString;
+use Tempest\View\Attributes\AttributeFactory;
+use Tempest\View\Elements\ElementFactory;
 use Tempest\View\Exceptions\ViewCompilationFailed;
 use Tempest\View\Exceptions\ViewVariableWasReserved;
 use Tempest\View\GenericView;
@@ -26,9 +29,38 @@ public function __construct(
         private readonly TempestViewCompiler $compiler,
         private readonly ViewCache $viewCache,
         private readonly ViewConfig $viewConfig,
-        private readonly Container $container,
+        private readonly ?Container $container,
     ) {}
 
+    public static function make(
+        ?ViewConfig $viewConfig = null,
+        ?ViewCache $viewCache = null,
+        Environment $environment = Environment::PRODUCTION,
+    ): self {
+        $viewConfig ??= new ViewConfig();
+
+        $elementFactory = new ElementFactory(
+            $viewConfig,
+            $environment,
+        );
+
+        $compiler = new TempestViewCompiler(
+            elementFactory: $elementFactory,
+            attributeFactory: new AttributeFactory(),
+        );
+
+        $elementFactory->setViewCompiler($compiler);
+
+        $viewCache ??= ViewCache::disabled();
+
+        return new self(
+            compiler: $compiler,
+            viewCache: $viewCache,
+            viewConfig: $viewConfig,
+            container: null,
+        );
+    }
+
     public function __get(string $name): mixed
     {
         return $this->currentView?->get($name);
@@ -58,8 +90,12 @@ public function render(string|View $view): string
     private function processView(View $view): View
     {
         foreach ($this->viewConfig->viewProcessors as $viewProcessorClass) {
-            /** @var \Tempest\View\ViewProcessor $viewProcessor */
-            $viewProcessor = $this->container->get($viewProcessorClass);
+            if ($this->container) {
+                /**  @var \Tempest\View\ViewProcessor $viewProcessor */
+                $viewProcessor = $this->container->get($viewProcessorClass);
+            } else {
+                $viewProcessor = new $viewProcessorClass();
+            }
 
             $view = $viewProcessor->process($view);
         }

packages/view/src/ViewCache.php

@@ -20,6 +20,22 @@ public function __construct(
         );
     }
 
+    public static function enabled(?string $path = null): self
+    {
+        return new self(
+            enabled: true,
+            pool: new ViewCachePool($path ?? __DIR__ . '/../.tempest/cache'),
+        );
+    }
+
+    public static function disabled(?string $path = null): self
+    {
+        return new self(
+            enabled: false,
+            pool: new ViewCachePool($path ?? __DIR__ . '/../.tempest/cache'),
+        );
+    }
+
     public function clear(): void
     {
         $this->pool->clear();