[1.1] Compile time rendering

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Adds a new "Compile Time Rendering" system, which can render components at compile time and inline the static output
 - Adds compiler support for circular component references, like nested comment threads
 - Adds a `#cache` compiler attribute, which may be used to cache the results of any Dagger component
 - Bumps the minimum Laravel version to `11.23`, for `Cache::flexible` support

README.md

@@ -70,6 +70,10 @@ The main visual difference when working with Dagger components is the use of the
 - [Dynamic Components](#dynamic-components)
 - [Custom Component Paths and Namespaces](#custom-component-paths-and-namespaces)
   - [Blade Component Prefix](#blade-component-prefix)
+- [Compile Time Rendering](#compile-time-rendering)
+  - [Disabling Compile Time Rendering on a Component](#disabling-compile-time-rendering-on-a-component)
+  - [Enabling/Disabling Optimizations on Classes or Methods](#enablingdisabling-optimizations-on-classes-or-methods)
+  - [Notes on Compile Time Rendering](#notes-on-compile-time-rendering)
 - [The View Manifest](#the-view-manifest)
 - [License](#license)
 
@@ -1389,6 +1393,151 @@ Custom components can leverage all features of the Dagger compiler using their c
 
 You are **not** allowed to register the prefix `x` with the Dagger compiler; attempting to do so will raise an `InvalidArgumentException`.
 
+## Compile Time Rendering
+
+The Dagger compiler contains a subsystem known as the Compile Time Renderer, or CTR. This checks to see if all the props on a component are resolvable at runtime; if so, it may elect to compile the component at runtime and insert the pre-rendered results into Blade's compiled output.
+
+This feature has a number of internal safe guards, and here are a few of the things that will internally disable this feature:
+
+- Dynamic/interpolated variable references
+- Using Mixins
+- Most static method calls
+- Referencing PHP's [superglobals](https://php.net/superglobals), such as `$_GET` or `$_POST`
+- Using debugging-related functions in a component, such as `dd`, `dump`, `var_dump`, etc.
+- Calling functions such as `time`, `now`, or `date`
+- Enabling the Attribute Cache on a component
+- Components with slots
+
+Imagine we have the following alert component:
+
+```blade
+<!-- /resources/dagger/views/alert.blade.php -->
+
+@props(['type' => 'info', 'message'])
+
+<div {{ $attributes->merge(['class' => 'alert alert-'.$type]) }}>
+    {{ $message }}
+</div>
+```
+
+If we were to call the alert component like so:
+
+```blade
+<c-alert message="My awesome message" />
+```
+
+The compiler would detect that all props are resolvable, and the following would be emitted in the compiled Blade output:
+
+```html
+<div class="alert alert-info">
+    The awesome message
+</div>
+```
+
+However, if we were to call our component like so, the compiler would not attempt to render the component at compile time:
+
+```blade
+<c-alert :$message />
+```
+
+### Disabling Compile Time Rendering on a Component
+
+The CTR system should be transparent from a component author's point-of-view, however, if the rare event that you need to disable compiler optimizations, you may do so using the `compiler` helper method:
+
+```blade
+<!-- /resources/dagger/views/the_component.blade.php -->
+@php
+    \Stillat\Dagger\component()
+        ->props(['title'])
+        ->compiler(
+            allowOptimizations: false
+        );
+@endphp
+
+{{ $title }}
+```
+
+If you find yourself disabling optimizations on a component, please open a discussion or an issue with details on which behaviors led to that decision.
+
+### Enabling/Disabling Optimizations on Classes or Methods
+
+The CTR system will aggressively disable itself whenever it detects static method calls within component templates. You may choose to mark these methods as safe using the `EnableOptimization` attribute:
+
+```php
+<?php
+
+namespace App;
+
+use Stillat\Dagger\Compiler\EnableOptimization;
+
+class MyAwesomeClass
+{
+
+    #[EnableOptimization]
+    public static function myHelper()
+    {
+
+    }
+
+}
+```
+
+You may also mark an entire class as safe for optimizations by applying the attribute to the class instead:
+
+```php
+<?php
+
+namespace App;
+
+use Stillat\Dagger\Compiler\EnableOptimization;
+
+#[EnableOptimization]
+class MyAwesomeClass
+{
+
+    public static function myHelper()
+    {
+
+    }
+
+}
+```
+
+If you'd like to *disable* optimizations on a class or method explicitly, you may use the `DisableOptimization` attribute instead.
+
+The following example would enable optimizations on the entire class but disable it on a specific method:
+
+```php
+<?php
+
+namespace App;
+
+use Stillat\Dagger\Compiler\DisableOptimization;
+use Stillat\Dagger\Compiler\EnableOptimization;
+
+#[EnableOptimization]
+class MyAwesomeClass
+{
+
+    public static function methodOne()
+    {
+        // Optimization allowed.
+    }
+
+    #[DisableOptimization]
+    public static function methodTwo()
+    {
+        // Optimization not allowed.
+    }
+
+}
+```
+
+### Notes on Compile Time Rendering
+
+- You should *never* attempt to force a component to render at compile time, outside of applying the `EnableOptimization` or `DisableOptimization` attributes to your own helper methods
+- If an exception is raised while rendering a component at compile time, CTR will be disabled for that component and the compiler will revert to normal behavior
+
 ## The View Manifest
 
 You may have noticed JSON files being written to your compiled view folder. These files are created by Dagger's "view manifest", which tracks dependencies of compiled views.

config/dagger.php

@@ -0,0 +1,17 @@
+<?php
+
+return [
+    'ctr' => [
+        'unsafe_variables' => [
+            '$_GET', '$_POST', '$_FILES', '$_REQUEST', '$_SESSION',
+            '$_ENV', '$_COOKIE', '$http_response_header', '$argc', '$argv',
+        ],
+        'unsafe_functions' => [
+            'now', 'time', 'date', 'env', 'getenv', 'cookie',
+            'request', 'session', 'dd', 'dump', 'var_dump',
+            'debug_backtrace', 'phpinfo', 'extract',
+            'get_defined_vars', 'parse_str', 'abort', 'abort_if',
+            'abort_unless',
+        ],
+    ],
+];

src/AbstractComponent.php

@@ -4,6 +4,7 @@
 
 use Illuminate\Support\Fluent;
 use Illuminate\View\ComponentAttributeBag;
+use Stillat\Dagger\Exceptions\RuntimeException;
 use Stillat\Dagger\Parser\ComponentTap;
 use Stillat\Dagger\Runtime\SlotContainer;
 
@@ -96,6 +97,14 @@ abstract public function trimOutput(): static;
 
     abstract public function cache(): static;
 
+    /**
+     * @throws RuntimeException
+     */
+    public function compiler(?bool $allowOptimizations = null): static
+    {
+        throw new RuntimeException('Cannot call compiler method at runtime.');
+    }
+
     public function __get(string $name)
     {
         return $this->data->get($name);

src/Compiler/ComponentState.php

@@ -6,6 +6,7 @@
 use InvalidArgumentException;
 use Stillat\BladeParser\Nodes\Components\ComponentNode;
 use Stillat\Dagger\Cache\CacheProperties;
+use Stillat\Dagger\ComponentOptions;
 use Stillat\Dagger\Support\Utils;
 
 class ComponentState
@@ -63,17 +64,36 @@ class ComponentState
 
     public string $validationMessages = '[]';
 
+    public ?bool $canCompileTimeRender = null;
+
     public int $lineOffset = 0;
 
+    public ?Extractions $extractions = null;
+
+    public ComponentOptions $options;
+
+    /**
+     * Indicates if the component is eligible for compile-time rendering.
+     *
+     * We will keep it false by default, and only enable this if needed.
+     */
+    public bool $isCtrEligible = false;
+
     public ?CacheProperties $cacheProperties = null;
 
     public function __construct(
         public ?ComponentNode $node,
         public string $varSuffix,
     ) {
+        $this->options = new ComponentOptions;
         $this->updateNodeDetails($this->node, $this->varSuffix);
     }
 
+    public function getDynamicVariables(): array
+    {
+        return $this->dynamicVariables;
+    }
+
     /**
      * @internal
      */
@@ -287,6 +307,11 @@ public function setPropDefaults(array $defaults): static
         return $this;
     }
 
+    public function getAllPropNames(): array
+    {
+        return array_merge($this->getPropNames(), $this->getAwareVariables());
+    }
+
     public function getPropDefaults(): array
     {
         return $this->defaultPropValues;
@@ -342,6 +367,11 @@ public function setMixins(string $classes): static
         return $this;
     }
 
+    public function hasMixins(): bool
+    {
+        return $this->mixins != '';
+    }
+
     public function getMixins(): string
     {
         return $this->mixins;

src/Compiler/Concerns/ManagesComponentCtrState.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace Stillat\Dagger\Compiler\Concerns;
+
+use PhpParser\NodeTraverser;
+use PhpParser\NodeVisitor\ParentConnectingVisitor;
+use Stillat\Dagger\Compiler\Ctr\CompileTimeRendererVisitor;
+use Stillat\Dagger\Parser\PhpParser;
+
+trait ManagesComponentCtrState
+{
+    protected ?CompileTimeRendererVisitor $ctrVisitor = null;
+
+    public function getCtrVisitor(): CompileTimeRendererVisitor
+    {
+        if ($this->ctrVisitor) {
+            return $this->ctrVisitor;
+        }
+
+        return $this->ctrVisitor = new CompileTimeRendererVisitor;
+    }
+
+    protected function containsOtherComponents(string $template): bool
+    {
+        preg_match_all(
+            '/<([a-zA-Z0-9_]+)([-:])[a-zA-Z0-9_\-:]*(?:\s[^>]*)?>/',
+            $template,
+            $matches,
+            PREG_SET_ORDER
+        );
+
+        if (! $matches) {
+            return false;
+        }
+
+        foreach ($matches as $match) {
+            if (! in_array(mb_strtolower($match[1]), $this->componentNamespaces)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    protected function checkForCtrEligibility(string $originalTemplate, string $compiledTemplate): void
+    {
+        if (! $this->activeComponent->options->allowOptimizations) {
+            $this->activeComponent->isCtrEligible = false;
+
+            return;
+        }
+
+        if ($this->containsOtherComponents($originalTemplate)) {
+            $this->activeComponent->isCtrEligible = false;
+
+            return;
+        }
+
+        $traverser = new NodeTraverser;
+
+        $ast = PhpParser::makeParser()->parse($compiledTemplate);
+        $parentingVisitor = new ParentConnectingVisitor;
+        $traverser->addVisitor($parentingVisitor);
+        $traverser->traverse($ast);
+
+        $traverser->removeVisitor($parentingVisitor);
+
+        $ctrVisitor = $this->getCtrVisitor()
+            ->reset()
+            ->setComponentState($this->activeComponent);
+
+        $traverser->addVisitor($ctrVisitor);
+        $traverser->traverse($ast);
+
+        $this->activeComponent->isCtrEligible = $ctrVisitor->isEligibleForCtr();
+    }
+}