feat(wpmc S5): Helpers::without_url_filters bypass counter

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

includes/class-helpers.php

@@ -9,6 +9,7 @@ final class Helpers
     private static bool $current_town_resolved = false;
     private static array $term_cache = [];
     private static array $page_unic_cache = [];
+    private static int $bypass_depth = 0;
 
     public static function reset_cache(): void
     {
@@ -16,6 +17,7 @@ final class Helpers
         self::$current_town_resolved = false;
         self::$term_cache = [];
         self::$page_unic_cache = [];
+        self::$bypass_depth = 0;
     }
 
     public static function get_term_by_slug(string $slug, string $taxonomy = 'town'): ?\WP_Term
@@ -177,4 +179,19 @@ final class Helpers
         }
         return true;
     }
+
+    public static function without_url_filters(callable $fn)
+    {
+        self::$bypass_depth++;
+        try {
+            return $fn();
+        } finally {
+            self::$bypass_depth--;
+        }
+    }
+
+    public static function is_bypassed(): bool
+    {
+        return self::$bypass_depth > 0;
+    }
 }

tests/HelpersTest.php

@@ -347,4 +347,61 @@ final class HelpersTest extends TestCase
 
         self::assertTrue(true);
     }
+
+    public function test_is_bypassed_returns_false_by_default(): void
+    {
+        self::assertFalse(Helpers::is_bypassed());
+    }
+
+    public function test_without_url_filters_returns_callback_value_and_keeps_depth_zero(): void
+    {
+        $result = Helpers::without_url_filters(function () {
+            self::assertTrue(Helpers::is_bypassed());
+            return 'inner-value';
+        });
+
+        self::assertSame('inner-value', $result);
+        self::assertFalse(Helpers::is_bypassed());
+    }
+
+    public function test_without_url_filters_decrements_depth_on_exception(): void
+    {
+        try {
+            Helpers::without_url_filters(function () {
+                throw new \RuntimeException('boom');
+            });
+            self::fail('Expected RuntimeException');
+        } catch (\RuntimeException $e) {
+            self::assertSame('boom', $e->getMessage());
+        }
+
+        self::assertFalse(Helpers::is_bypassed());
+    }
+
+    public function test_without_url_filters_supports_nesting(): void
+    {
+        Helpers::without_url_filters(function () {
+            self::assertTrue(Helpers::is_bypassed());
+
+            Helpers::without_url_filters(function () {
+                self::assertTrue(Helpers::is_bypassed());
+            });
+
+            // After inner exits, outer scope still bypassed.
+            self::assertTrue(Helpers::is_bypassed());
+        });
+
+        self::assertFalse(Helpers::is_bypassed());
+    }
+
+    public function test_reset_cache_clears_bypass_depth(): void
+    {
+        $reflection = new \ReflectionClass(Helpers::class);
+        $prop = $reflection->getProperty('bypass_depth');
+        $prop->setValue(null, 5);
+
+        Helpers::reset_cache();
+
+        self::assertFalse(Helpers::is_bypassed());
+    }
 }