From 50a3ed096e31cf6af2b0b29280ff055d2fb62e6b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ey=C3=BCp=20Can=20Akman?= <eyupcanakman@gmail.com>
Date: Tue, 24 Feb 2026 13:28:50 +0300
Subject: [PATCH] feat(filter_by): add helper to escape filter string values

---
 README.md                      | 11 +++++++++++
 src/FilterBy.php               | 11 +++++++++++
 tests/Feature/FilterByTest.php | 28 ++++++++++++++++++++++++++++
 3 files changed, 50 insertions(+)
 create mode 100644 src/FilterBy.php
 create mode 100644 tests/Feature/FilterByTest.php

diff --git a/README.md b/README.md
index ebf82379..14b2a2b7 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,17 @@ Read the documentation here: [https://typesense.org/api/](https://typesense.org/
 
 Here are some examples that walk you through how to use the client: [doc/examples](examples)
 
+### Escaping filter values
+
+Use `Typesense\FilterBy::escapeString()` to safely use string values in `filter_by`:
+
+```php
+use Typesense\FilterBy;
+
+$filterValue = "The 17\" O'Conner && O`Series \n OR a || 1%2 book? (draft), [alpha]";
+$filterBy = 'tags:=' . FilterBy::escapeString($filterValue);
+```
+
 ## Compatibility
 
 | Typesense Server | typesense-php |
diff --git a/src/FilterBy.php b/src/FilterBy.php
new file mode 100644
index 00000000..9fba16a8
--- /dev/null
+++ b/src/FilterBy.php
@@ -0,0 +1,11 @@
+<?php
+
+namespace Typesense;
+
+class FilterBy
+{
+    public static function escapeString(string $value): string
+    {
+        return '`' . str_replace('`', '\\`', $value) . '`';
+    }
+}
diff --git a/tests/Feature/FilterByTest.php b/tests/Feature/FilterByTest.php
new file mode 100644
index 00000000..3a91603f
--- /dev/null
+++ b/tests/Feature/FilterByTest.php
@@ -0,0 +1,28 @@
+<?php
+
+namespace Feature;
+
+use PHPUnit\Framework\TestCase;
+use Typesense\FilterBy;
+
+class FilterByTest extends TestCase
+{
+    public function testEscapesSpecialCharactersByWrappingInBackticks(): void
+    {
+        $rawFilterValue = "The 17\" O'Conner && O`Series \n OR a || 1%2 book? (draft), [alpha]";
+
+        $escapedFilterValue = FilterBy::escapeString($rawFilterValue);
+
+        $this->assertSame(
+            "`The 17\" O'Conner && O\\`Series \n OR a || 1%2 book? (draft), [alpha]`",
+            $escapedFilterValue
+        );
+    }
+
+    public function testEscapesMultipleBackticksWithinAFilterString(): void
+    {
+        $escapedFilterValue = FilterBy::escapeString('`left` and `right`');
+
+        $this->assertSame('`\\`left\\` and \\`right\\``', $escapedFilterValue);
+    }
+}