[6.x] Antlers HTML instrumentation

config/antlers.php

@@ -15,6 +15,41 @@
 
     'debugbar' => env('STATAMIC_ANTLERS_DEBUGBAR', true),
 
+    /*
+    |--------------------------------------------------------------------------
+    | Tracing
+    |--------------------------------------------------------------------------
+    |
+    | When tracing is enabled, every tracer listed here is resolved from the
+    | container and notified as every Antlers node is entered and exited.
+    |
+    */
+
+    'tracing' => env('STATAMIC_ANTLERS_TRACING', false),
+
+    'tracers' => [],
+
+    /*
+    |--------------------------------------------------------------------------
+    | HTML Instrumentation
+    |--------------------------------------------------------------------------
+    |
+    | When enabled, rendered Antlers regions are wrapped in HTML comments and
+    | attributes that point back to the templates they came from. Analysis
+    | is cached by template content; set "cache" to false to skip that.
+    |
+    */
+
+    'instrumentation' => [
+        'enabled' => env('STATAMIC_ANTLERS_INSTRUMENTATION', false),
+        'cache' => env('STATAMIC_ANTLERS_INSTRUMENTATION_CACHE', true),
+        'comments' => true,
+        'prefix' => 'antlers',
+        'attributes' => [],
+        'metadata' => [],
+        'componentPrefixes' => [],
+    ],
+
     /*
     |--------------------------------------------------------------------------
     | Guarded Variables

src/Contracts/View/Instrumentation/ComposesRenderedOutput.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace Statamic\Contracts\View\Instrumentation;
+
+interface ComposesRenderedOutput
+{
+}

src/Facades/Antlers.php

@@ -10,6 +10,7 @@
  * @method static Parser parser()
  * @method static mixed usingParser(Parser $parser, \Closure $callback)
  * @method static AntlersString parse(string $str, array $variables = [], bool $trusted = false)
+ * @method static AntlersString parseWithoutInstrumentation(string $str, array $variables = [], bool $trusted = false)
  * @method static string parseLoop(string $content, array $data, bool $supplement = true, array $context = [], bool $trusted = false)
  * @method static array identifiers(string $content)
  *

src/Forms/Tags.php

@@ -6,6 +6,7 @@
 use DebugBar\DebugBarException;
 use Illuminate\Support\Collection;
 use Statamic\Contracts\Forms\Form as FormContract;
+use Statamic\Contracts\View\Instrumentation\ComposesRenderedOutput;
 use Statamic\Facades\Antlers;
 use Statamic\Facades\Blink;
 use Statamic\Facades\Blueprint;
@@ -19,7 +20,7 @@
 use Statamic\Tags\Tags as BaseTags;
 use Statamic\View\Antlers\Language\Runtime\GlobalRuntimeState;
 
-class Tags extends BaseTags
+class Tags extends BaseTags implements ComposesRenderedOutput
 {
     use Concerns\GetsFormSession,
         Concerns\GetsQueryResults,

src/Modifiers/CoreModifiers.php

@@ -135,7 +135,7 @@ public function antlers($value, $params, $context)
     {
         $trusted = Arr::get($params, 0) === 'trusted' && ! GlobalRuntimeState::$isEvaluatingUserData;
 
-        return (string) Antlers::parse($value, $context, $trusted);
+        return (string) Antlers::parseWithoutInstrumentation($value, $context, $trusted);
     }
 
     /**

src/Providers/EventServiceProvider.php

@@ -27,6 +27,7 @@ class EventServiceProvider extends ServiceProvider
             \Statamic\Listeners\ClearState::class,
         ],
         \Illuminate\Foundation\Http\Events\RequestHandled::class => [
+            \Statamic\View\Instrumentation\RemoveMisplacedMarkersFromResponse::class,
             \Statamic\Listeners\ClearState::class,
         ],
         \Illuminate\Console\Events\CommandFinished::class => [

src/Providers/ViewServiceProvider.php

@@ -28,6 +28,7 @@
 use Statamic\View\Cascade;
 use Statamic\View\Debugbar\AntlersProfiler\PerformanceCollector;
 use Statamic\View\Debugbar\AntlersProfiler\PerformanceTracer;
+use Statamic\View\Instrumentation\InstrumentationManager;
 use Statamic\View\Interop\Stacks;
 
 class ViewServiceProvider extends ServiceProvider
@@ -85,6 +86,8 @@ private function registerAntlers()
             return new PerformanceTracer();
         });
 
+        $this->app->singleton(InstrumentationManager::class);
+
         $this->app->bind(ParserContract::class, function ($app) {
             /** @var RuntimeParser $parser */
             $parser = $app->make(RuntimeParser::class)->cascade($app[Cascade::class]);
@@ -152,14 +155,16 @@ private function registerAntlers()
             }
 
             if ($this->profilerEnabled()) {
-                if (! $isTracingOn) {
+                if ($runtimeConfig->traceManager === null) {
                     $runtimeConfig->traceManager = new TraceManager();
                     $runtimeConfig->isTracingEnabled = true;
                 }
 
                 $runtimeConfig->traceManager->registerTracer(app(PerformanceTracer::class));
             }
 
+            $app->make(InstrumentationManager::class)->applyTo($runtimeConfig);
+
             $parser->isolateRuntimes(GlobalRuntimeState::$requiresRuntimeIsolation)
                 ->setRuntimeConfiguration($runtimeConfig);
 

src/StaticCaching/Middleware/Cache.php

@@ -22,6 +22,7 @@
 use Statamic\StaticCaching\NoCache\Session;
 use Statamic\StaticCaching\Replacer;
 use Statamic\StaticCaching\ResponseStatus;
+use Statamic\View\Antlers\Language\Facades\Runtime;
 use Symfony\Component\HttpFoundation\Response as SymfonyResponse;
 
 use function Statamic\trans as __;
@@ -213,11 +214,19 @@ private function canBeCached($request)
             return false;
         }
 
+        if (Runtime::instrumenting()) {
+            return false;
+        }
+
         return true;
     }
 
     private function shouldBeCached($request, $response)
     {
+        if (Runtime::instrumenting()) {
+            return false;
+        }
+
         // Only GET requests should be cached. For instance, Live Preview hits frontend URLs as
         // POST requests to preview the changes. We don't want those to trigger any caching,
         // or else pending changes will be shown immediately, even without hitting save.

src/StaticCaching/NoCache/StringFragment.php

@@ -5,6 +5,7 @@
 use Statamic\Facades\File;
 use Statamic\Support\Arr;
 use Statamic\Support\Str;
+use Statamic\View\Antlers\Language\Runtime\RuntimeParser;
 
 class StringFragment
 {
@@ -32,6 +33,8 @@ public function render(): string
 
         $this->data['__frontmatter'] = Arr::pull($this->data, 'view', []);
 
+        $this->data[RuntimeParser::CAPTURED_CONTENT] = true;
+
         $rendered = view('nocache::'.$view, $this->data)->render();
 
         File::delete($path);

src/StaticCaching/NoCache/Tags.php

@@ -2,10 +2,11 @@
 
 namespace Statamic\StaticCaching\NoCache;
 
+use Statamic\Contracts\View\Instrumentation\ComposesRenderedOutput;
 use Statamic\Facades\Antlers;
 use Statamic\StaticCaching\Middleware\Cache;
 
-class Tags extends \Statamic\Tags\Tags
+class Tags extends \Statamic\Tags\Tags implements ComposesRenderedOutput
 {
     public static $handle = 'nocache';
     public static $stack = 0;

src/Tags/Cache.php

@@ -6,6 +6,7 @@
 use Statamic\Facades\Site;
 use Statamic\Facades\URL;
 use Statamic\View\Antlers\Language\Runtime\LiteralReplacementManager;
+use Statamic\View\Antlers\Language\Runtime\RuntimeParser;
 use Statamic\View\Antlers\Language\Runtime\StackReplacementManager;
 use Statamic\View\State\CachesOutput;
 
@@ -68,6 +69,10 @@ private function isEnabled()
             return false;
         }
 
+        if ($this->parser instanceof RuntimeParser && $this->parser->instrumenting()) {
+            return false;
+        }
+
         return true;
     }
 

src/Tags/ComponentProxy.php

@@ -9,6 +9,7 @@
 use Illuminate\View\ComponentAttributeBag;
 use Illuminate\View\DynamicComponent;
 use ReflectionClass;
+use Statamic\View\Instrumentation\InstrumentationState;
 use Throwable;
 
 class ComponentProxy extends Tags
@@ -35,11 +36,15 @@ public function setParameters($parameters)
     public function index()
     {
         $___obLevel = ob_get_level();
+        $__env = null;
+        $renderIncremented = false;
+        $componentStackPushed = false;
 
         try {
             $__env = $this->context['__env'] ?? view();
 
             $__env->incrementRender();
+            $renderIncremented = true;
 
             $componentName = $this->params['component_name___'];
             $tagCompiler = $this->makeComponentTagCompiler();
@@ -93,22 +98,38 @@ public function index()
                 ]);
 
                 self::$componentStack[] = [$component, $contextData];
+                $componentStackPushed = true;
 
-                echo $this->parse($contextData);
+                echo InstrumentationState::withoutInstrumentation(
+                    fn () => $this->parse($contextData)
+                );
             }
 
-            $result = $__env->renderComponent();
+            $result = InstrumentationState::withinComponentView(
+                fn () => $__env->renderComponent()
+            );
 
             $__env->decrementRender();
+            $renderIncremented = false;
             $__env->flushStateIfDoneRendering();
 
-            if ($this->content) {
+            if ($componentStackPushed) {
                 array_pop(self::$componentStack);
+                $componentStackPushed = false;
             }
 
             return ltrim($result);
         } catch (Throwable $e) {
             $this->handleViewException($e, $___obLevel);
+        } finally {
+            if ($componentStackPushed) {
+                array_pop(self::$componentStack);
+            }
+
+            if ($renderIncremented && $__env !== null) {
+                $__env->decrementRender();
+                $__env->flushStateIfDoneRendering();
+            }
         }
     }
 
@@ -125,7 +146,9 @@ public function componentSlot()
 
             $__env->slot($slot, null, $this->escapeBoundAttributes($context));
 
-            echo $this->parse($contextData);
+            echo InstrumentationState::withoutInstrumentation(
+                fn () => $this->parse($contextData)
+            );
 
             $__env->endSlot();
         } catch (Throwable $e) {

src/Tags/Concerns/RendersViews.php

@@ -3,9 +3,14 @@
 namespace Statamic\Tags\Concerns;
 
 use Illuminate\Support\HtmlString;
+use Statamic\View\Antlers\AntlersString;
+use Statamic\View\Antlers\Language\Facades\Runtime;
+use Statamic\View\Instrumentation\InstrumentationState;
 
 trait RendersViews
 {
+    protected ?string $instrumentedSlotContent = null;
+
     protected function viewName($partial)
     {
         $partial = str_replace('/', '.', $partial);
@@ -49,7 +54,11 @@ protected function shouldRender(): bool
 
     protected function getSlotContent(): HtmlString|string
     {
-        $content = trim($this->parse());
+        $parsed = $this->parse();
+
+        [$content, $this->instrumentedSlotContent] = Runtime::splitMarkers(
+            $parsed instanceof AntlersString ? $parsed->instrumented() : (string) $parsed
+        );
 
         if ($this->isAntlersBladeComponent()) {
             return new HtmlString($content);
@@ -58,6 +67,24 @@ protected function getSlotContent(): HtmlString|string
         return $content;
     }
 
+    protected function withInstrumentedSlot(array $variables): array
+    {
+        $key = InstrumentationState::twinsKey();
+        $outputs = $variables[$key] ?? [];
+
+        unset($outputs['slot'], $variables[$key]);
+
+        if ($this->instrumentedSlotContent !== null && is_string($variables['slot'] ?? null)) {
+            $outputs['slot'] = [$variables['slot'], $this->instrumentedSlotContent];
+        }
+
+        if ($outputs !== []) {
+            $variables[$key] = $outputs;
+        }
+
+        return $variables;
+    }
+
     /**
      * The {{ exists }} tag.
      *

src/Tags/IncludeTag.php

@@ -83,7 +83,7 @@ protected function render($view)
 
         $cascade = Cascade::toArray();
 
-        $scope = array_merge(
+        $scope = $this->withInstrumentedSlot(array_merge(
             $this->params->bool('cascade') ? $cascade : [],
             $data,
             $this->resolveSlots($parameters, $data, $isBlade),
@@ -92,7 +92,7 @@ protected function render($view)
                 '__frontmatter' => $data,
             ],
             $isBlade ? [self::CONTEXT_KEY => true] : []
-        );
+        ));
 
         $hadViews = array_key_exists('views', $cascade);
         $viewsState = $cascade['views'] ?? null;

src/Tags/Partial.php

@@ -25,10 +25,10 @@ protected function render($partial)
 
         $context = array_diff_key($this->context->all(), array_flip(IncludeTag::VIEW_DATA_KEYS));
 
-        $variables = array_merge($context, $this->params->all(), [
+        $variables = $this->withInstrumentedSlot(array_merge($context, $this->params->all(), [
             '__frontmatter' => $this->params->all(),
             'slot' => $this->isPair ? $this->getSlotContent() : null,
-        ]);
+        ]));
 
         return view($this->viewName($partial), $variables)
             ->withoutExtractions()

src/View/Antlers/Antlers.php

@@ -6,6 +6,7 @@
 use Statamic\Contracts\View\Antlers\Parser;
 use Statamic\View\Antlers\Language\Parser\IdentifierFinder;
 use Statamic\View\Antlers\Language\Runtime\GlobalRuntimeState;
+use Statamic\View\Instrumentation\InstrumentationState;
 
 class Antlers
 {
@@ -29,17 +30,23 @@ public function usingParser(Parser $parser, Closure $callback)
 
     public function parse($str, $variables = [], $trusted = false)
     {
-        $parser = $this->parser();
         $previousState = GlobalRuntimeState::$isEvaluatingUserData;
         GlobalRuntimeState::$isEvaluatingUserData = ! $trusted;
 
         try {
-            return $parser->parse($str, $variables);
+            return $this->parser()->parse($str, $variables);
         } finally {
             GlobalRuntimeState::$isEvaluatingUserData = $previousState;
         }
     }
 
+    public function parseWithoutInstrumentation($str, $variables = [], $trusted = false)
+    {
+        return InstrumentationState::withoutInstrumentation(
+            fn () => $this->parse($str, $variables, $trusted)
+        );
+    }
+
     /**
      * Iterate over an array and parse the string/template for each.
      *