feat: skip HTML/JS injection for partial requests

Author: datamweb

app/Config/Toolbar.php

@@ -1,5 +1,14 @@
 <?php
 
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
 namespace Config;
 
 use CodeIgniter\Config\BaseConfig;
@@ -119,4 +128,31 @@ class Toolbar extends BaseConfig
     public array $watchedExtensions = [
         'php', 'css', 'js', 'html', 'svg', 'json', 'env',
     ];
+
+    /**
+     * --------------------------------------------------------------------------
+     * Ignored HTTP Headers
+     * --------------------------------------------------------------------------
+     *
+     * CodeIgniter Debug Toolbar normally injects HTML and JavaScript into every
+     * HTML response. This is correct for full page loads, but it breaks requests
+     * that expect only a clean HTML fragment.
+     *
+     * Libraries like HTMX, Unpoly, and Hotwire (Turbo) update parts of the page or
+     * manage navigation on the client side. Injecting the Debug Toolbar into their
+     * responses can cause invalid HTML, duplicated scripts, or JavaScript errors
+     * (such as infinite loops or "Maximum call stack size exceeded").
+     *
+     * Any request containing one of the following headers is treated as a
+     * client-managed or partial request, and the Debug Toolbar injection is skipped.s
+     *
+     * @var list<string>
+     */
+    public array $disableOnHeaders = [
+        'HX-Request',        // HTMX partial requests
+        'HX-Boosted',        // HTMX boosted navigation
+        'X-Unpoly-Request',  // Unpoly partial requests
+        'Turbo-Frame',       // Turbo Frames
+        'Turbo-Visit',       // Turbo Drive navigation
+    ];
 }

system/Debug/Toolbar.php

@@ -42,6 +42,12 @@ class Toolbar
      */
     protected $config;
 
+    /**
+     * Indicates if the current request is a custom AJAX-like request
+     * (HTMX, Unpoly, Turbo, etc.) that expects clean HTML fragments.
+     */
+    protected bool $isCustomAjax = false;
+
     /**
      * Collectors to be used and displayed.
      *
@@ -365,10 +371,8 @@ protected function roundTo(float $number, int $increments = 5): float
 
     /**
      * Prepare for debugging.
-     *
-     * @return void
      */
-    public function prepare(?RequestInterface $request = null, ?ResponseInterface $response = null)
+    public function prepare(?RequestInterface $request = null, ?ResponseInterface $response = null): void
     {
         /**
          * @var IncomingRequest|null $request
@@ -385,7 +389,9 @@ public function prepare(?RequestInterface $request = null, ?ResponseInterface $r
                 return;
             }
 
-            $toolbar = service('toolbar', config(ToolbarConfig::class));
+            $config = config(ToolbarConfig::class);
+
+            $toolbar = service('toolbar', $config);
             $stats   = $app->getPerformanceStats();
             $data    = $toolbar->run(
                 $stats['startTime'],
@@ -407,10 +413,17 @@ public function prepare(?RequestInterface $request = null, ?ResponseInterface $r
 
             $format = $response->getHeaderLine('content-type');
 
+            foreach ($config->disableOnHeaders as $header) {
+                if ($request->hasHeader($header)) {
+                    $this->isCustomAjax = true;
+                    break;
+                }
+            }
+
             // Non-HTML formats should not include the debugbar
             // then we send headers saying where to find the debug data
             // for this response
-            if ($request->isAJAX() || ! str_contains($format, 'html')) {
+            if ($request->isAJAX() || ! str_contains($format, 'html') || $this->isCustomAjax) {
                 $response->setHeader('Debugbar-Time', "{$time}")
                     ->setHeader('Debugbar-Link', site_url("?debugbar_time={$time}"));
 
@@ -454,10 +467,8 @@ public function prepare(?RequestInterface $request = null, ?ResponseInterface $r
      * Inject debug toolbar into the response.
      *
      * @codeCoverageIgnore
-     *
-     * @return void
      */
-    public function respond()
+    public function respond(): void
     {
         if (ENVIRONMENT === 'testing') {
             return;