From 67de6dab754ff6df7547228e1ecb9b10f33669cc Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 6 Jul 2026 17:35:58 -0500
Subject: [PATCH] feat: add output escaping helpers

---
 src/Http/Escape.php            | 27 ++++++++++++++
 tests/Unit/Http/EscapeTest.php | 64 ++++++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+)
 create mode 100644 src/Http/Escape.php
 create mode 100644 tests/Unit/Http/EscapeTest.php

diff --git a/src/Http/Escape.php b/src/Http/Escape.php
new file mode 100644
index 0000000..69ea427
--- /dev/null
+++ b/src/Http/Escape.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http;
+
+final class Escape
+{
+    public static function html(mixed $value): string
+    {
+        if ($value === null) {
+            return '';
+        }
+
+        return htmlspecialchars((string) $value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
+    }
+
+    public static function attr(mixed $value): string
+    {
+        return self::html($value);
+    }
+
+    public static function url(string $value): string
+    {
+        return rawurlencode($value);
+    }
+}
diff --git a/tests/Unit/Http/EscapeTest.php b/tests/Unit/Http/EscapeTest.php
new file mode 100644
index 0000000..4e61c38
--- /dev/null
+++ b/tests/Unit/Http/EscapeTest.php
@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Http;
+
+use BattleForge\Http\Escape;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+final class EscapeTest extends TestCase
+{
+    #[DataProvider('htmlProvider')]
+    public function testItEscapesHtmlContext(mixed $input, string $expected): void
+    {
+        self::assertSame($expected, Escape::html($input));
+    }
+
+    /**
+     * @return iterable<string, array{mixed, string}>
+     */
+    public static function htmlProvider(): iterable
+    {
+        yield 'plain' => ['hello', 'hello'];
+        yield 'less-than' => ['<script>', '&lt;script&gt;'];
+        yield 'ampersand' => ['a & b', 'a &amp; b'];
+        yield 'double-quote' => ['she said "hi"', 'she said &quot;hi&quot;'];
+        yield 'single-quote' => ["it's", 'it&#039;s'];
+        yield 'invalid-utf8-substituted' => ["a\xC0\x80b", "a\xEF\xBF\xBD\xEF\xBF\xBDb"];
+        yield 'integer' => [42, '42'];
+        yield 'null' => [null, ''];
+    }
+
+    #[DataProvider('attrProvider')]
+    public function testItEscapesAttributeContext(mixed $input, string $expected): void
+    {
+        self::assertSame($expected, Escape::attr($input));
+    }
+
+    /**
+     * @return iterable<string, array{mixed, string}>
+     */
+    public static function attrProvider(): iterable
+    {
+        yield 'tag-breakout' => ['" onclick="', '&quot; onclick=&quot;'];
+        yield 'apostrophe' => ["' onclick='", '&#039; onclick=&#039;'];
+    }
+
+    #[DataProvider('urlProvider')]
+    public function testItEncodesUrls(string $input, string $expected): void
+    {
+        self::assertSame($expected, Escape::url($input));
+    }
+
+    /**
+     * @return iterable<string, array{string, string}>
+     */
+    public static function urlProvider(): iterable
+    {
+        yield 'space' => ['hello world', 'hello%20world'];
+        yield 'slash' => ['a/b', 'a%2Fb'];
+        yield 'unicode' => ['héllo', 'h%C3%A9llo'];
+    }
+}