Better Twig exception handling

Author: riasvdv

src/Providers/CraftServiceProvider.php

@@ -18,6 +18,7 @@
 use CraftCms\Cms\Section\SectionServiceProvider;
 use CraftCms\Cms\Structure\StructureServiceProvider;
 use CraftCms\Cms\Translation\TranslationServiceProvider;
+use CraftCms\Cms\Twig\TwigServiceProvider;
 use CraftCms\Cms\Updates\UpdatesServiceProvider;
 use CraftCms\Cms\User\UserServiceProvider;
 use Illuminate\Support\AggregateServiceProvider;
@@ -30,6 +31,7 @@ final class CraftServiceProvider extends AggregateServiceProvider
         TranslationServiceProvider::class,
         DatabaseServiceProvider::class,
         ViewServiceProvider::class,
+        TwigServiceProvider::class,
         ProjectConfigServiceProvider::class,
         DeprecatorServiceProvider::class,
         LicenseServiceProvider::class,

src/Twig/TwigMapper.php

@@ -0,0 +1,96 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CraftCms\Cms\Twig;
+
+use Craft;
+use Illuminate\Support\Collection;
+use ReflectionProperty;
+use Throwable;
+use Twig\Error\RuntimeError;
+use Twig\Template;
+
+final readonly class TwigMapper
+{
+    /**
+     * Maps an exception and replaces all references to compiled Twig
+     * templates in the stack trace with references to the original source.
+     */
+    public function map(Throwable $exception): Throwable
+    {
+        if ($exception instanceof RuntimeError) {
+            /**
+             * When we get a Twig runtime error, we need the previous exception to be shown.
+             */
+            $exception = $exception->getPrevious() ?? $exception;
+        }
+
+        $viewIndex = null;
+
+        $trace = collect($exception->getTrace())
+            ->map(function (array $frame, int $index) use (&$viewIndex) {
+                $templateInfo = $this->resolveTemplatePathAndLine($frame['file'] ?? '', $frame['line']);
+
+                if ($templateInfo !== false) {
+                    [$frame['file'], $frame['line']] = $templateInfo;
+
+                    $viewIndex ??= $index;
+                }
+
+                return $frame;
+            })
+            ->when(
+                $viewIndex !== null && str_ends_with($exception->getFile(), '.twig'),
+                fn (Collection $trace) => $trace->slice($viewIndex + 1)  // Remove all traces before the view
+            )
+            ->all();
+
+        $traceProperty = new ReflectionProperty('Exception', 'trace');
+        $traceProperty->setValue($exception, $trace);
+
+        return $exception;
+    }
+
+    /**
+     * Attempts to resolve a compiled template file path and line number to its source template path and line number.
+     *
+     * @param  string  $path  The compiled template path
+     * @param  int|null  $line  The line number from the compiled template
+     * @return array|false The resolved template path and line number, or `false` if the path couldn’t be determined.
+     *                     If a template path could be determined but not the template line number, the line number will be null.
+     */
+    public function resolveTemplatePathAndLine(string $path, ?int $line): array|false
+    {
+        if (! str_contains($path, 'compiled_templates')) {
+            return false;
+        }
+
+        $contents = file_get_contents($path);
+
+        if (! preg_match('/^class (\w+)/m', $contents, $match)) {
+            return false;
+        }
+
+        $class = $match[1];
+        if (! class_exists($class, false) || ! is_subclass_of($class, Template::class)) {
+            return false;
+        }
+
+        $template = new $class(Craft::$app->getView()->getTwig());
+        $src = $template->getSourceContext();
+        $templatePath = $src->getPath() ?: null;
+        $templateLine = null;
+
+        if ($line !== null) {
+            foreach ($template->getDebugInfo() as $codeLine => $thisTemplateLine) {
+                if ($codeLine <= $line) {
+                    $templateLine = $thisTemplateLine;
+                    break;
+                }
+            }
+        }
+
+        return [$templatePath, $templateLine];
+    }
+}

src/Twig/TwigServiceProvider.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CraftCms\Cms\Twig;
+
+use Exception;
+use Illuminate\Contracts\Debug\ExceptionHandler;
+use Illuminate\Support\ServiceProvider;
+
+final class TwigServiceProvider extends ServiceProvider
+{
+    #[\Override]
+    public function register(): void
+    {
+        $this->app->make(ExceptionHandler::class)->map(Exception::class, fn (Exception $e) => $this->app->make(TwigMapper::class)->map($e));
+    }
+}

yii2-adapter/legacy/helpers/Template.php

@@ -14,6 +14,7 @@
 use craft\web\View;
 use CraftCms\Cms\Shared\BaseModel;
 use CraftCms\Cms\Support\Facades\Entries;
+use CraftCms\Cms\Twig\TwigMapper;
 use Illuminate\Support\Facades\Auth;
 use Stringable;
 use Twig\Environment;
@@ -360,40 +361,11 @@ public static function js(string $js, array $options = [], ?string $key = null):
      * @return array|false The resolved template path and line number, or `false` if the path couldn’t be determined.
      * If a template path could be determined but not the template line number, the line number will be null.
      * @since 4.1.5
+     * @deprecated 6.0.0 use {@see TwigMapper::resolveTemplatePathAndLine()} instead.
      */
     public static function resolveTemplatePathAndLine(string $path, ?int $line)
     {
-        if (!str_contains($path, 'compiled_templates')) {
-            return false;
-        }
-
-        $contents = file_get_contents($path);
-
-        if (!preg_match('/^class (\w+)/m', $contents, $match)) {
-            return false;
-        }
-
-        $class = $match[1];
-        if (!class_exists($class, false) || !is_subclass_of($class, TwigTemplate::class)) {
-            return false;
-        }
-
-        /** @var TwigTemplate $template */
-        $template = new $class(Craft::$app->getView()->getTwig());
-        $src = $template->getSourceContext();
-        $templatePath = $src->getPath() ?: null;
-        $templateLine = null;
-
-        if ($line !== null) {
-            foreach ($template->getDebugInfo() as $codeLine => $thisTemplateLine) {
-                if ($codeLine <= $line) {
-                    $templateLine = $thisTemplateLine;
-                    break;
-                }
-            }
-        }
-
-        return [$templatePath, $templateLine];
+        return app(TwigMapper::class)->resolveTemplatePathAndLine($path, $line);
     }
 
     /**