debug, help: escape </xmp so values can't break out of the wrapper

Author: daveedis

CHANGELOG.md

@@ -159,6 +159,9 @@ These still work, they're just no longer featured in the docs - no changes requi
 
 ### Other
 
+- The `<xmp>` wrapper on `help()`'s web output escapes a literal `</xmp` as
+  `<\/xmp`, same as CMSB's `xmp_safe()` - keeps the shared helper in sync
+  with SmartArray's `debug()` fix (the help text itself is static)
 - Misc internal code cleanup and modernization
 
 ## [2.6.3] - 2026-04-27

docs/method-reference.md

@@ -97,15 +97,15 @@ default when a field is empty.*
 ### [Require a Value](conditionals-and-error-checking.md#requiring-a-value---or404-ordie-orthrow-orredirect)
 
 *Use these for values that must exist, like a record ID from the URL. If the
-value is missing (null or "") they stop the page; otherwise they do nothing and
-the chain continues. Zero counts as present.*
+value is missing (null or "") they stop the page; otherwise the chain
+continues. Zero counts as present.*
 
 | Method                  | Description                                                                          |
 |-------------------------|--------------------------------------------------------------------------------------|
 | `->orDie($text)`        | Outputs the message and exits                                                        |
 | `->or404($text = null)` | Outputs a 404 header and the message (default: standard not-found text), then exits  |
 | `->orThrow($text)`      | Throws a RuntimeException with the message                                           |
-| `->orRedirect($url)`    | Redirects to `$url` and exits (throws RuntimeException if headers were already sent) |
+| `->orRedirect($url)`    | Redirects to `$url` and exits. The headers-already-sent check throws even when the value is present, so misuse fails on the first request |
 
 ### [Value Checks](conditionals-and-error-checking.md#truefalse-checks---isempty-isnotempty-ismissing-isnull)
 

src/SharedHelpers.php

@@ -133,7 +133,8 @@ private static function xmpWrap(string $output): string
             return $plain;
         }
 
-        return "\n<xmp>\n$output\n</xmp>\n";
+        // escape "</xmp" so output can't break out of the block, same as CMSB's xmp_safe()
+        return "\n<xmp>\n" . str_ireplace('</xmp', '<\/xmp', $output) . "\n</xmp>\n";
     }
 
 }

tests/Support/bin/xmp-breakout.php

@@ -0,0 +1,15 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Web target for HelpTest: prints xmpWrap() output for text holding a
+ * literal </xmp> closing tag. Run under PHP's built-in server (php -S),
+ * whose cli-server SAPI takes the <xmp>-wrapping web branch that CLI
+ * tests can't reach. xmpWrap() is private, so this calls it by reflection
+ * (help()'s own output is static doc links, nothing injectable).
+ */
+
+require dirname(__DIR__, 3) . '/vendor/autoload.php';
+
+$xmpWrap = new ReflectionMethod(\Itools\SmartString\SmartString::class, 'xmpWrap');
+echo $xmpWrap->invoke(null, '</xmp><script>alert(1)</script>');

tests/Unit/HelpTest.php

@@ -9,7 +9,8 @@
 /**
  * help() is deprecated: it prints links to the online docs, plain (no <xmp>)
  * on CLI. The <xmp> wrap only happens for text/html web responses, which
- * can't be simulated in-process (xmpWrap reads PHP_SAPI).
+ * can't be simulated in-process (xmpWrap reads PHP_SAPI); one test reaches
+ * it through PHP's built-in server.
  *
  * n/a dimensions: encoding, global settings, immutability, argument matrix
  * ($value passes through untouched by design).
@@ -39,4 +40,53 @@ public function testHelpReturnsValuePassthroughOnBothCallForms(): void
         $this->assertSame('original value', $instanceResult);
         $this->assertSame($staticOutput, $instanceOutput);
     }
+
+    /**
+     * The <xmp> web branch is reachable under PHP's built-in server (SAPI
+     * cli-server), so this is the one test that asserts the wrapped path: a
+     * literal </xmp> can't end the block early - it displays as <\/xmp>, the
+     * same escaping as CMSB's xmp_safe().
+     */
+    public function testXmpWrapEscapesXmpClosingTagOnWebResponses(): void
+    {
+        $body = $this->requestViaBuiltInServer('xmp-breakout.php');
+
+        $this->assertStringContainsString('<xmp>', $body);
+        $this->assertStringContainsString('<\/xmp><script>alert(1)</script>', $body, 'payload displays escaped');
+        $this->assertSame(1, substr_count($body, '</xmp>'), 'only the wrapper itself closes the block');
+    }
+
+    /**
+     * Serve one Support/bin script through php -S and return the response
+     * body. The built-in server is the one place tests can reach xmpWrap()'s
+     * web branch (PHP_SAPI is 'cli' everywhere else in the suite).
+     */
+    private function requestViaBuiltInServer(string $script): string
+    {
+        $docRoot = dirname(__DIR__) . '/Support/bin';
+
+        // find a free port, then hand it to php -S (it can't pick its own)
+        $socket = stream_socket_server('tcp://127.0.0.1:0');
+        $this->assertNotFalse($socket, 'could not find a free port');
+        $port = (int)substr(strrchr(stream_socket_get_name($socket, false), ':'), 1);
+        fclose($socket);
+
+        $pipes  = [];
+        $server = proc_open([PHP_BINARY, '-S', "127.0.0.1:$port", '-t', $docRoot], [1 => ['pipe', 'w'], 2 => ['pipe', 'w']], $pipes);
+        $this->assertIsResource($server, 'could not start php -S');
+
+        try {
+            $context = stream_context_create(['http' => ['timeout' => 1]]);
+            $body    = false;
+            for ($attempt = 0; $attempt < 50 && $body === false; $attempt++) {
+                usleep(100_000);
+                $body = @file_get_contents("http://127.0.0.1:$port/$script", false, $context);
+            }
+            $this->assertIsString($body, 'no response from php -S after 5 seconds');
+            return $body;
+        } finally {
+            proc_terminate($server);
+            proc_close($server);
+        }
+    }
 }